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FOREWORD 


The  comprehensive  Computer-Aided  Design  Environment 
(COMRADE)  software  system  has  been  developed  at  the  David  W. 
Taylor  Naval  Ship  Research  and  Development  Center,  sponsored  by 
the  Naval  Sea  Systems  Command  (NAVSEA,  formerly  NAVSHIPS)  in 
support  of  their  Computer-Aided  Ship  Design  and  Construction 
(CASDAC)  effort  to  facilitate  the  design  and  construction  of 
Naval  vehicles.  Although  conceived  in  support  of  ship  design, 
the  COMRADE  software  has  been  developed  for  use  as  a general 
design  tool.  Three  separate  components  are  included:  the 
COMRADE  Executive  System;  the  COMRADE  Data  Management  System; 
and  the  COMRADE  Design  Administration  System.  All  of  these 
components  are  operable  on  the  DTNSRDC  Control  Data  6700 
computing  system  (SCOPE  3.4  operating  system)  and  are  documented 
in  a set  of  eight  DTSNRDC  reports: 

COMRADE  - The  Computer-Aided  Design  Environment  Project, 

An  Introduction 

COMRADE  Executive  System  Users  Manual 

COMRADE  Data  Storage  Facility  Users  Manual 

COMRADE  Absolute  Subroutine  Utility  Users  Manual 

COMRADE  Data  Management  System  Primer 

COMRADE  Data  Management  System  Host  Language  Interface 
Users  Manual 

COMRADE  Data  Management  System  Conversational  Interface 
Users  Manual 

COMRADE  Design  Administration  System  Users  Manual 
Inquiries  concerning  any  of  the  components  of  the  COMRADE 
system  should  be  directed  to  the  Computer  Systems  Development 
Group,  Computer  Sciences  Division,  DTNSRDC. 

It  is  understood  and  agreed  that  the  U.S.  Government  shall 
not  be  liable  for  any  loss  or  damage  incurred  from  the  use  of 
these  computer  programs. 
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I.  INTRODUCTION  TO  THE  COMRADE  DATA  MANAGEMENT  SYSTEM 

A.  SYSTEM  CLASSIFICATION  AND  ORIENTATION 

Generalized  data  base  management  systems  might  be  classi- 
fied as  either  self-contained  or  host  language  interface  types. 
A self-contained  system  typically  provides  generalized  capa- 
bilities for  data  definition,  data  maintenance,  data  retrieval, 
and  report  formatting.  In  addition,  a self-contained  system 
usually  provides  a generalized  retrieval  language  that  can 
be  used  to  express  fairly  complex  selection  criteria.  In 
contrast,  a host  language  system  provides  a generalized 
capability  only  for  data  definition,  and  an  interface, 
composed  of  a set  of  high-level  calls,  which  may  be 
embedded  in  application  programs  written  in  procedure 
languages  such  as  FORTRAN  or  COBOL.  It  is  via  these 
specialized  application  programs  that  the  end  user  of 
a host  language  data  base  system  performs  data  maintenance, 
query  processing,  and  report  formatting  procedures. 

Although  an  application  program  interface  to  the  data 
base  is  always  provided  by  a host  language  system,  such 
an  interface  may  be  included  in  a self-contained  type 
of  system  as  has  been  done  in  the  data  management  component 
of  the  Computer-Aided  Design  Environment  (COMRADE)  System. 

The  COMRADE  system, ^ developed  at  the  David  W.  Taylor 
Naval  Ship  Research  and  Development  Center  (DTNSRDC)  in 

^Rhodes , T . , "COMRADE  - The  Computer-Aided  Design  Environ- 
ment Project  - An  Introduction,"  DTNSRDC  Report  76-0001. 
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support  of  the  Computer-Aided  Ship  Design  and  Construction 
(CASDAC)  Project,^  provides  a self-contained  type  of  data 

case  management  system  which  includes  the  host  language  i 

interface  described  in  the  pages  that  follow.  This  system, 

I 

called  the  COMRADE  Data  Management  System  (CDMS),  is  designed  f 

to  enable  non-computer-oriented  personnel  to  define,  load, 

update,  and  query  a data  base.  Moreover,  it  supports  a host  | 

language  interface  to  FORTRAN,  COBOL,  and  COMPASS  assemoly 

i 

language  programs  so  that  when  specialized  needs  arise--as 

frequently  happens  with  CASDAC  application  software,  for  ! 

example — application  programs  can  be  developed  to  interact  } 

■ 

as  necessary  with  the  data  base.  The  host  language  interface  > 

j 

is  therefore  an  important  component  of  CDMS.  ■ 

i 

CDMS  was  developed  in  the  FORTRAN  Extended  programming  ! 

language  and  is  intended  primarily  for  use  in  scientific  j 

f 

r 

applications.  It  was  designed  to  facilitate  management  of  1 

numeric  information  used  in  applications  involving  the  design  ' 

and  construction  of  ships,  aircraft,  buildings,  dams,  and 
oridges,  among  others.  Although  CDMS  does  provide  for  the 
use  of  textual  values,  it  does  not  facilitate  the  query  and 

maintenance  of  textual  data  as  would  be  required  for  biblio-  f 

graphic  and  legal  applications.  | 

2 

"Naval  Ship  Systems  Command  Technical  Development  Plan  - 
Computer-Aided  Ship  Design  and  Construction,"  NAVSHIPS  Report 
S46-33X  ( Feb  1970)  . 
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CDMS  is  opeciitional  under  the  SCOPE  3.4  operating  system^ 
on  the  DTNSRDC  Control  Data  6700  computing  facility 
(Figure  1).  CDMS  was  developed  by,  and  is  maintained  and 
enhanced  by,  the  Computer  Systems  Development  Group,  Computer 
Sciences  Division,  DTNSRDC. 

B.  TRI-LEVEL  ARCHITECTURE 

CDMS  is  hierarchically  structured  into  three  levels.  Users 
are  permitted  access  to  their  data  at  any  of  the  three  levels. 
The  flexibility  provided  by  such  a design  permits  the  indi- 
vidual user  to  make  his  own  trade-offs  between  ease  of  use  of 
the  system  and  computational  efficiency. 

The  lowest-level  CDMS  component,  the  COMRADE  Data 
Storage  Facility  (CDSF),'*  supports  storage,  retrieval, 
modification,  and  deletion  of  named  variable-length 
logical  records  or  data  blocks,  and  the  optional  building 
and  processing  of  inverted  data  lists  for  retrieval  of 
information  based  on  data  values.  The  subroutines  of  CDSF 
are  generally  used  by  the  system  programmer  who  values 
economy  of  computer  time  and  space  above  all  else.  CDSF 
constitutes  the  foundation  for  higher-level  CDMS  components. 

The  next  higher  level  CDMS  component  comprises  a set  of 
host  language  subroutines  which  serve  as  the  interface 


Control  Data  Corporation,  "SCOPE  Reference  Manual,  6000 
Version  3.4,"  Publication  No.  60307200. 

^ Wallace,  M.,  et  al . , "COMRADE  Data  Storage  Facility  Users 
Manual,"  DTNSRDC  Report  76-0003. 
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between  an  application  program's  data  requirements  and  CDSF. 


It  is  at  this  level  that  logical  items  of  information  and 


groups  of  information  may  be  retrieved  and  updated  by  name. 


Information  may  also  be  retrieved  by  way  of  queries  involving 


keyed  data  attributes.  Variable-length  logical  records  may 


be  defined  as  groups  of  single-valued  elements,  arrays,  and 


repeating  groups  of  elements.  Pointer-type  elements  may  be 


used  to  link  records  to  form  a variety  of  logical  data 


structures . 


The  third  and  highest  level  CDMS  component  is  provided 


to  make  the  system  most  usable  to  non-computer -or iented 


personnel.  This  component  comprises  a set  of  modules  suitable 


for  use  in  batch  mode  but  designed  primarily  for  conversational 


use.  In  the  conversational  mode,  a user  seated  at  a keyboard/ 


printer  or  display  terminal  may  define,  load,  update,  and 


interrogate  his  data  base.  As  with  the  host  language  interface. 


the  conversational  interface  allows  a user  to  work  with  logical 


Items  of  information.  While  performing  data  base  retrieval,  a 


user  specifies  his  selection  criteria  in  English-like  phrases. 


All  of  the  CDMS  conversational  commands  are  available  to  any 


valid  user  of  DTNSRDC's  INTERCOM  time-sharing  system. 


The  performance  of  data  base  definition  and  processing  at 


each  of  the  three  levels  of  CDMS  is  depicted  in  Figure  2. 


■Gorham,  W.,  et  al.,  "COMRADE  Data  Management  System  Con- 
versational Interface  Users  Manual,"  DTNSRDC  Report  76-0007, 


^Control  Data  Coporation,  "INTERCOM  Reference  Manual,  6000 
Version  4,"  Publication  No.  60307100. 
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STEP  1 - DATA  DEFINITION 


C.  BASIC  CONCEPTS  AND  TERMINOLOGY 


• DATA  BLOCK.  The  basic  unit  of  data  storage  within  a 
CDMS  data  base  is  the  data  block.  Each  data  block  is  assigned 
a unique  name  of  as  many  as  eight  characters,  the  first  of 
which  must  be  a letter,  which  is  used  in  all  retrieval  and 
update  transactions  involving  information  in  that  block.  Thus, 
for  example,  in  a data  base  of  information  about  U.S.  Presidents, 
data  pertaining  to  John  F.  Kennedy  might  conceivably  be 
collected  into  a data  block  given  the  name  KENNEDY;  and 
similatily,  within  a ship  design  file,  information  about  a 
particular  deck  would  likely  be  grouped  into  a data  block 
given  a name  such  as  DK03. 

. BLOCK  TYPE.  A CDMS  data  base  file  comprises  one  or  more 
sets  of  data  blocks.  Each  set  has  a unique  record  format  or 
definition  called  a "block  type"  description.  This  description 
gives  the  logical  structure  of  all  data  blocks  of  that  parti- 
cular block  type.  The  description  defines  subblocks,  repeating 
groups,  and  data  elements  and  defines  the  data  type  (i.e.,  single- 
or  multi-valued,  alphanumeric,  pointer,  real,  and  integer)  and 
inversion  status  of  each  element.  A U.S.  Presidents  data  base, 
for  example,  might  have  38  data  blocks  of  the  block  type  PRES 
(personal  information  about  the  Presidents)  and  48  data  blocks 
of  the  block  type  ELECTION  (information  pertaining  to  presiden- 
tial elections ) . 

To  further  illustrate  the  block  type  concept,  assume  that 
the  personnel  department  of  a large  installation  has  a data 
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base  containing  personal  data  on  each  of  the  installation's 
employees.  Personal  data  for  an  employee  named  Tom  Jones 
might  be  stored  in  a data  block  names  JONES,  and  personal  data 
for  an  employee  named  John  Smith  stored  in  a data  block  named 
SMITH.  Although  this  data  base  may  include  many  data  blocks, 
all  blocks  storing  personal  data  will  be  of  the  same  block 
type  perhaps  named  EMPLOYEE.  The  block-type  description  for 
the  EMPLOYEE  blocks  indicates  the  kinds  of  data  values  con- 
tained in  that  set  of  data  blocks.  The  description  may,  for 
instance,  indicate  that  the  third  data  value  in  the  data 
blocks  JONES,  SMITH,  etc.,  is  the  integer  value  for  the  data 
element  AGE,  and  that  the  fifth  data  value  in  each  of  these 
data  blocks  is  the  alphanumeric  value  for  the  element 
BIRTHDAY. 

. SUBBLOCK . For  convenience  in  organizing  and  retrieving 
data  elements,  a data  block  can  be  subdivided  into  uniquely 
named  groups  of  data  elements  known  as  subblocks.  Subblocks 
may  be  used  to  group  logically  related  elements  and  to  provide 
access  to  subsets  of  data  values  within  a data  block.  Each 
data  block  may  contain  as  many  as  eight  subblocks.  A subblock 
name  may  be  as  many  as  eight  alphanumeric  characters  long, 
i the  first  always  a letter. 

DATA  ELEMENT.  In  CDMS,  the  data  element  is  the 
smallest  unit  of  data  that  can  be  defined  and  referred  to  by 
name  (the  name  to  be  as  many  as  eight  characters  long,  with 
the  first  a letter).  There  are  three  classes  of  data 
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ele[nents--numer  ic , alphanumeric,  and  pointer: 

(a)  A numeric  data  element  may  contain  either  real  or  integer 
values,  and  may  be  either  a single-valued  quantity 
(represented  by  a single  60-bit  CDC  6000  computer  word)  or  a 
variable-length  array  of  such  values.  If  an  array  of  values 

is  given,  the  data  element  name  will  refer  to  all  of  the 
values  in  the  array.  The  CDMS  host  language  subroutines  do, 
however,  provide  a means  of  referring  to  a particular  array 
element  if  its  position  within  the  array  is  provided. 

(b)  An  alphanumeric  data  element  may  be  either  a single 
value  (made  up  of  as  many  as  ten  CDC  6000  display  code 
characters),  an  array  of  such  values,  or  a variable-length 
text  string. 

(c)  Pointer  data  elements  are  used  to  construct  a data 
structure  (tree,  ring,  network)  that  links  all  related  data 
blocks.  A pointer  element  in  one  data  block  may  "point"  to 
a different  data  block  on  the  same  data  base  file,  or  it 
may  "point"  to  a data  block  stored  on  a different  data  base 
file  entirely.  A pointer  data  element  may  be  defined 
either  as  a single  value  or  an  array  of  values. 

. REPEATING  GROUP.  Within  a data  block,  one  to  50 
consecutively-defined  data  elements  of  the  same  or  different 
type  may  be  grouped  together  and  defined  as  a repeating 
group.  A repeating  group  is  identified  by  a name  (as  many 
as  eight  characters,  beginning  with  a letter)  which  may  be 
used  when  referring  to  the  entire  grouping  of  data  elements. 


i 


t 

i 

i 

> 

f 

Each  element  in  the  group  may,  of  course,  be  referenced  by 
[ its  own  individual  name. 

A data  block  may  contain  a variable  number  of  repetitions 
or  occurrences  of  repeating  group  values.  Although  there  may 
, be  at  most  50  data  elements  in  a repeating  group,  the  number 

of  occurrences  of  values  for  these  elements  is  virtually  limit- 
less. 

To  illustrate  the  repeating  group  concept,  assume  that 
; employee  Tom  Jones  has  three  children  and  employee  John  Smith 

i has  but  one  child.  If  in  a block  type  named  EMPLOYEE  there 

I exists  a repeating  group  named  CHILDREN,  and  if  CHILDREN 

includes  the  data  elements  NAME  and  AGE,  then  in  the  data 
block  named  JONES  there  would  be  three  occurrences  of 
CHILDREN  (i.e.,  NAME  and  AGE)  while  in  the  data  block  named 
SMITH  there  would  be  only  one  occurrence. 

INVERTED  DATA  ELEMENT.  Quick  resolution  of  conditional 
retrieval  requests  or  "queries"  issued  from  either  conver- 
sational terminals  or  application  programs  is  an  important 
aspect  of  data  base  processing.  CDMS  uses  a set  of  "inverted 
lists"  to  minimize  query  response  times.  An  inverted  list 
is  a directory  which  (1)  contains  the  data  values  for  a 
particular  data  element  which  was  assigned  inversion  status 
when  it  was  defined,  and  (2)  contains  the  names  of  all  data 
blocks  having  values  for  the  inverted  elements.  The  data- 
value/block-name  pairs  are  sorted  by  value. 
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To  illustrate,  assume  a CDMS  data  base  of  personnel 


data.  Assume  also  that  the  data  base  contains  data  blocks 
of  the  names  JONES,  SMITH,  JOHNSON,  BROWN,  and  WILSON,  which 
contain  personal  data  on  Tom  Jones,  John  Smith,  Jim  Johnson, 
Ed  Brown  and  Bob  Wilson,  respectively.  If  in  the  block  type 
EMPLOYEE  there  is  a data  element  AGE  which  has  been  assigned 
inversion  status,  values  for  the  element  AGE  will  be  stored 
in  an  inverted  list  which  might  look  as  follows: 


AGE 

Smith 

Johnson 

Brown 

Jones 

Wilson 


25 

28 

28 

36 

38 


If  the  user  requested  a printout  of  the  values  for  the  data 
element  WEIGHT  (another  data  element  within  EMPLOYEE)  for 
all  persons  at  least  30  years  of  age,  the  inverted  list  for 
AGE  would  be  examined,  and  only  those  data  blocks  satisfying 
the  condition  - namely,  JONES  and  WILSON  - selected  for  further 
processing  to  obtain  WEIGHT  information. 

. LOCALLY  DEFINED  DATA  ELEMENTS.  An  individual  data  block 
may  include  data  elements  not  logically  related  to  other  blocks 
of  the  same  block  type.  These  locally  defined  data  elements 
are  managed  in  exactly  the  same  way  as  the  other  data  elements 
defined  within  a block  type  description  except  that  they  are 
not  considered  for  membership  within  repeating  groups. 


11 


1 


• CROSS  FILE  REFERENCE  TABLE.  In  addition  to  containing 
user-defined  data  blocks,  block  types,  and  inverted  lists,  a 
CDMS  data  base  file  contains  a cross-file  reference  table 
which  lists  the  permanent  file  names  of  all  data  base  files 
"pointed  to"  by  pointer  data  elements  contained  within  this 
particular  file.  The  permanent  files  listed  in  the  table  may 
be  one  of  two  types:  a SCOPE  permanent  file,  indicated  by  a 
four-character  ID  and  a file  name  of  as  many  as  40  characters, 
or  a CPFMS  (COMRADE  Permanent  File  Management  System)  file, 
indicated  by  level-three  and  level-four  names.  (See  Appendix 
A for  a detailed  description  of  the  CPFMS  file  management 
capab  il  ity . ) 

D.  SYSTEM  FEATURES  AND  CAPABILITIES 

To  facilitate  the  comparison  of  CDMS  features  with  other 
generalized  data  base  management  systems,  the  following 
feature  analysis  has  been  patterned  after  that  of  the  CODASYL 

7 

Technical  Report  of  May  1971  and  after  the  National  Bureau 
of  Standards  Technical  Note  887  of  November  1975  (a  com- 

g 

parison  of  six  generalized  data  base  management  systems). 
Features  are  described  under  eight  major  headings:  computer 
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CODASYL  Systems  Committee,  "Feature  Analysis  of  Generalized 
Data  Base  Management  Systems,"  CODASYL  Systems  Committee 
Report  ( May  1971). 


environment,  data  structures,  data  definition,  data  maintenance, 
query  specification,  output  and  report  generation,  security 
features,  and  external  linkages.  Each  heading  is  further  sub- 
divided as  necessary  to  provide  greater  detail. 

1.  Computer  Environment 

CDMS  is  operational  on  the  DTNSRDC  Control  Data  6700 
computing  facility  which  is  supported  by  the  SCOPE  3.4 
operating  system.  The  core  requirement  for  the  conver- 
sational interface  approximates  25K  (decimal)  words.  The 
core  requirement,  excluding  buffer  space,  for  the  host 
language  interface  and  the  COMRADE  Data  Storage  Facility 

g 

(when  used  with  the  COMRADE  Absolute  Subroutine  Utility) 
approximates  8K  (decimal)  words.  The  source  language 
for  most  of  CDMS  is  FORTRAN  Extended;  only  a very  small 
number  of  COMPASS  assembly  language  statements  have  been 
included . 

The  communication  link  between  the  terminal  user  and 
CDMS  is  supported  by  the  INTERCOM  time-sharing  system. 

CDMS  is  not  coded  re-entrantly . Its  components  may  be 
used  in  either  the  batch  or  the  conversational  mode. 

2.  Data  Structures 
. Data  Types 

CDMS  provides  a set  of  valid  data  types  which  can  be 
defined  for  single-valued  elements  and  array  elements.  Those 

^Wallace,  M.,  "Absolute  Subroutine  Utility  Users  Manual," 
DTNSRDC  Report  76-0004. 


13 


IT 


valid  types  are  numeric,  including  real  and  integer  values; 
alphanumeric,  including  a single  value  of  as  many  as  ten 
characters,  an  array  of  such  values,  and  a variable-length 
text  string;  and  pointer.  A character  may  be  any  letter, 
digit,  or  special  symbol  supported  by  the  hardware  (Appendix  B). 

. Logical  Data  Structure 

The  logical  data  structure  is  defined  as  the  composition 
of  data  elements  in  the  data  blocks,  and  the  interrelationships 
between  data  blocks  and  their  files  as  determined  by  the  user 
without  regard  for  main  memory  or  secondary  storage.  CDMS 
data  blocks  may  contain  single-valued  and  variable-length 
array  elements.  Variable-length  repeating  groups  are  also 
permitted.  Data  may  be  interrelated  across  files  and  among 
data  blocks  through  the  use  of  "pointers",  thereby  providing 
full  network  structuring.  Moreover,  inverted  list  structures 
are  supported  for  single-valued  elements. 

. Physical  Storage  Structure 

Data  records  within  CDMS  are  randomly  organized  and  are 
located  by  transforming  the  data  block  name  into  the  disk 
address.  This  type  of  transformation,  or  hashing  technique, 
makes  it  possible  to  access  a block  during  its  residence  on  a 
CDMS  file  by  its  symbolic  name  rather  than  through  a numerical 
index . 
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3.  Data  Definition 


CDMS  provides  the  user  with  a block  type  or  data  definition 
language.  This  language  serves  as  the  mechanism  for  defining 
data  elements,  repeating  groups,  subblocks,  and  keyed  or  in- 
verted elements.  The  language  is  card  oriented  - one  card 
image  tor  each  item  to  be  defined.  Within  a card  image,  fields 
may  be  specified  free-form  with  commas  separating  the  fields. 

4.  Data  Maintenance 

. Data  Base  Loading  and  Input  Analysis 

After  the  user  has  described  his  block  types  to  CDMS,  the 
system  uses  these  descriptions  to  construct  internal  block-type 
tables,  one  for  each  description.  At  data  base  load  time,  a 
block-type  table  is  identified  by  name,  after  which  one  or  more 
data  blocks  of  this  particular  block  type  may  be  created  and, 
optionally,  loaded  with  values.  After  a data  block  has  been 
created,  a value  that  is  to  be  loaded  into  that  block  must 
first  be  read  from  a sequentially  organized  card  image  file. 

If  the  value  is  numeric,  it  will  be  converted  into  the  proper 
internal  format  pursuant  to  the  data  element  definition  stored 
within  the  block-type  table.  After  conversion,  the  value  is 
located  into  the  data  block  and  referred  to  in  future  retrieval 
and  update  requests  simply  by  its  data  element  name.  A data 
definition  links  the  card  image  file  of  values  to  a particular 
set  of  block  types. 
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. Data  Base  Restructuring 

The  restructuring  of  a data  base  generally  involves  the 


1 


modification  of  the  block  type,  such  as  by  adding  or  deleting 
a data  element  or  repeating  group  definition.  Within  CDMS, 
data  base  restructuring  is  permitted  so  long  as  no  data  blocks 
have  been  created  for  a given  block  type.  Restructuring 
following  creation  of  data  blocks  involves  dumping  the  existing 
contents  of  these  blocks,  redefining  the  block  type,  and  re- 
loading the  dumped  values.  A utility  program  is  available 
under  CDMS  for  dumping  the  contents  of  a data  base. 

. Data  Updates 

Updating  is  the  process  of  adding,  modifying,  or  deleting 
the  contents  of  some  part  of  a data  base.  Updating  differs 
from  data  loading  in  that  the  load  process  is  typically  a batch 
procedure  involving  a sizable  quantity  of  values  and  the 
creation  of  new  data  blocks,  whereas  the  update  process  is 
typically  a conversational  procedure  involving  transactions 
on  existing  data  blocks  and  the  use  of  fairly  small  sets  of 
data  values.  In  CDMS,  there  is  a language  for  specifying 
update  transactions.  The  language  differs  from  the  query 
language  in  that  it  does  not  involve  English-like  phrases 
and  conditional  operations.  The  update  language  does,  however, 
provide  for  both  the  updating  and  the  printing  of  data 
elements.  The  language  is  card  oriented  - one  card  image  for 
each  update  or  print  operation.  Within  a card  image,  fields 
may  be  specified  free-form  separated  by  slashes. 
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. other  Maintenance  Capabilities 

Lockout  during  the  updating  or  loading  of  a CDMS  data  base 
is  maintained  at  the  file  level.  As  a result,  only  one  user  at 
a time  may  modify  a CDMS  data  base  file.  To  minimize  possible 
conflicts  resulting  from  concurrent  update  or  load  operations, 
the  scheduling  of  data  base  modifications  may  have  to  be  con- 
trolled administratively.  During  a modification  procedure, 
users  may  retrieve  and  print  data  base  values. 

5.  Query  Specification 

. Overall  User-System  Interaction  and  Search  Specification 

Query  processing  involves  the  selective  retrieval  of  data 
from  a data  base.  Within  CDMS,  information  is  entered  initially 
to  identify  the  particular  portion  of  the  data  base  to  be  in- 
terrogated. That  information  is  followed  by  a set  of  statements 
that  specify  selection  criteria  and  certain  actions  to  be  taken 
such  as  print  in  columnar  or  row  format,  for  example.  The 
query  language  is  based  upon  use  of  English-like  phrases  which 
may  contain  Boolean  combinations  (i.e.,  AND  or  OR)  of  relational 
expressions.  A relational  expression  in  most  instances  is 
a triple  composed  of  a data  element  name,  a relational  operator 
(i.e.,  GT,  GE,  LT,  LE,  NE  or  EQ),  and  one  data  value;  in  the 
case  of  the  operator  "between",  the  expression  is  composed 
of  a name,  the  operator  BET,  and  two  values. 

. Multi-File  Searching 

The  CDMS  Query  capability  enables  as  many  as  five  data  base 
files  to  be  searched  initially.  Cross-file  and  intrafile 
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pointer  elements  may  be  traversed.  With  the  current  "hit" 
file  (a  "hit"  file  is  a list  of  data  blocks  which  have  satisfied 
a specific  condition)  as  a starting  point,  as  many  as  eight 
different  pointers  (specified  in  a single  statement)  may  be 
processed  by  the  system.  Typically,  processing  of  cross-file 
pointers  will  continue  without  user  intervention. 

. Additional  Query  Features 

CDMS  allows  hit  files  to  be  named  and  saved  for  use  in 
subsequent  query  statements.  Searches  based  on  values  of  non- 
inverted  data  elements  may  he  conducted  on  the  data  blocks  named 
in  a hit  file.  A hit  file  name  table,  and  the  number  of  "hits" 
on  a hit  file,  will  be  printed  upon  request. 

A pseudo  batch  mode  is  available  to  the  user  during  con- 
versational query  processing.  In  this  mode,  the  user  may  submit 
a set  of  query  statements  which  will  then  be  checked  for  syntax 
errors;  if  there  ate  no  errors,  the  statements  will  be  executed 
without  further  user  intervention. 

6.  Output  and  Report  Generation 

. Language  Type  and  Media  Selection  Flexibility 

An  output  and  report  generation  capability  is  provided  as  a 
subset  of  the  CDMS  Query  capability.  English-like  phrasing  is 
used  to  specify  one  of  three  report  formats:  columnar,  row, 
or  simple  list.  Typically,  a report  is  printed  on  the  user's 
keyboard/printer  or  display  terminal.  Lengthy  reports  can  be 
routed  to  off-line  medium  and  high  speed  printers. 
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7.  Security  Features 

. File  Protection  and  Access  Control 

A CDMS  data  base  file  must  be  given  a name  (of  as  many  as 
40  characters),  and  may  be  password  protected  in  accordance 
with  SCOPE  3.4  operating  system  conventions.  The  file  is 
protected  from  unauthorized  access  by  way  of  a set  of  privacy 
controls  specified  at  the  time  the  file  is  cataloged  into  the 
SCOPE  system.  Since  access  priveleges  may  vary  from  user  to 
user,  a variety  of  controls  is  provided  including  read  only, 
read  and  modify,  increase  mass  storage  allocation,  and  delete 
a file  from  the  SCOPE  file  system. 

An  additional  level  of  CDMS  data  base  file  protection  may 
be  imposed  by  way  of  the  COMRADE  Permanent  File  Management 
System  (CPFMS).  A detailed  description  of  the  CPFMS  capability 
is  provided  in  Appendix  A. 


. File  Backup,  Recovery,  and  Restart 

At  DTNSRDC,  safeguards  exist  to  prevent  an  on-line  CDMS  file 
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from  being  accidentally  destroyed  during  normal  system 
operation  and  normal  loading  of  the  operating  system.  For 
backup  purposes  and  to  guard  against  data  being  lost  as  a 
result  of  some  abnormal  system  event,  on-line  files  are 
generally  dumped  to  magnetic  tape,  on  a semi-weekly  basis. 

A variety  of  utility  programs  exists  at  DTNSRDC  for  use  in 
more  frequent  dumping  of  data  base  files.  Among  these  is  the 
CDMS  conversational  interface  DUMP  module. 

8.  External  Linkages 

As  mentioned  previously,  CDMS  supports  a host  language 
interface  to  COBOL^®  FORTRAN  Extended*'^,  and  COMPASS  ^^appl  icat  ions 
programs.  These  programs  request  services  of  the  host  language 
subroutines  through  control  statements  such  as  the  CALL  state- 
ment of  FORTRAN  Extended,  for  example. 

E.  DATA  BASE  ADMINISTRATION 

In  an  environment  such  as  computer-aided  ship  design,  in 
which  the  data  base  includes  data  to  be  shared  by  many  users 
and  programs,  it  becomes  necessary  for  certain  functions  to 
be  centrally  coordinated  and  controlled.  In  such  an  environmer» 
the  data  base  must  inevitably  reflect  a compromise  between 


^^Control  Data  Corporation,  "COBOL  Version  4 Reference  Man  a 
Publication  No.  60384100. 

^^Control  Data  Corporation,  "FORTRAN  Extended  Version  4 Refer'  - 
Manual,"  Publication  No.  6035601. 

^^Control  Data  Corporation,  "COMPASS  Version  3 Reference  Man-^jj.," 
Publication  No.  60360900. 
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the  needs  of  the  various  competing  users  and  their  programs. 
Conflicts  resulting  from  such  diverse  needs  must  be  satis- 
factorily mediated  and  resolved.  Generally  this  role  of 
arbitrator  is  performed  by  a data  base  administrator  (DBA) 
who  possesses  data  processing  experience,  communications 
skills,  and  a working  familiarity  with  user  operations.  The 
DBA  is  responsible  for  functions  spanning  three  broad  categories 
of  data  base  design  and  management:  organization,  monitoring, 
and  reorganization. 

. ORGANIZATION . During  the  organization  of  a data  base 
the  DBA  assesses  the  needs  of  the  competing  users  and  programs. 
Following  a determination  of  all  the  data  requirements,  the 
DBA  will  (a)  use  the  block-type  definition  language  to  define 
the  logical  structure  of  the  data  base  including  those  subblocks, 
repeating  groups,  and  data  elements  that  serve  to  model  the 
problem  with  which  the  data  base  will  be  concerned;  (b)  co- 
ordinate data  base  loading  and  updating  activities;  (c)  assign 
lata  base  file  names  and  access  controls,  taking  into  account 

• arcess  privileges  of  all  data  base  users;  and  (d)  coordinate 

• I'-tivities  of  any  specialists  working  to  organize  the  data 

, .N ITOR  LNG . During  the  life  cycle  of  a data  base,  it 
^ DBA's  responsibility  to  develop  strategies  for  mon- 
• •'.1  the  use  of  the  data  base,  breach  of  privacy,  frequency 
= <.r,  and  reorganization. 
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REORGANIZATION.  As  a result  of  information  obtained  from 


the  monitoring  procedure,  or  because  of  the  changing  data  re- 
quirements of  the  users  and  their  programs,  the  DBA  may  find 
that  the  data  base  must  be  reorganized.  The  DBA  may:  (a)  change 
the  block-type  descriptions,  (b)  re-assign  access  controls,  (c) 
alter  the  frequency  of  backup  operations,  (d)  change  the  data 
base  contents  to  reflect  changes  in  the  block  types  and  the 
logical  data  structure,  and  (e)  remove  from  the  data  base  any 
allocated  storage  space  not  currently  being  used  productively. 

These  activities  indicate  the  kinds  of  functions  for  which 
the  DBA  and  his  staff  are  responsible.  Since  many  of  the  user 
languages  supported  by  CDMS  are  oriented  toward  non-computer 
personnel,  they  are  most  appropriate  for  use  by  the  DBA  and 
persons  working  under  his  direction  in  that  they  allow 
operations  to  be  readily  formulated  and  concisely  stated. 

F.  POSSIBLE  COURSE  OF  FURTHER  SYSTEM  DEVELOPMENT 

As  the  computer-aided  ship  design  systems  of  CASDAC  pro- 
gress from  the  planning  stage  to  the  developmental  stage, 
augmentation  of  CDMS  will  likely  be  required.  This  effort 
would  be  undertaken  along  two  fronts:  enhancement  of  CDMS 
features  and  capabilities  of  the  DTNSRDC  computing  facility, 
which  is  to  eventually  become  an  operating  mode  of  the  Navy 
laboratory  computing  network;  and  development  of  a subset 
of  CDMS  features  and  capabilities  on  a set  of  minicomputers 
which  are  to  be  located  at  the  Naval  Ship  Engineering  Center 
and  linked  to  the  DTNSRDC  computer. 
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II.  OVERVIEW  OF  THE  CDMS  HOST  LANGUAGE  INTERFACE 


A.  ROLE  OF  THE  INTERFACE 

The  CDMS  host  language  interface  serves  to  link  an 
application  program--a  ship  or  aircraft  design  program,  for 
example — with  a CDMS  data  base.  The  host  language  interface 
enables  the  program  to  create  sets  of  data  blocks,  to  retrieve 
and  update  data  block  information,  and  to  query  the  data  base, 
selectively  retrieving  data  that  satisfies  certain  user  speci- 
fied conditions.  When  combined  with  the  control  and  input/ 
output  constructs  of  a procedure  language  such  as  FORTRAN, 
the  host  language  interface  provides  a powerful,  responsive, 
data  base  processing  tool. 

Nineteen  subroutines  constitute  the  CDMS  host  language 
interface.  These  may  be  subdivided  functionionally  into  three 
groups : 

. Data  base  initialization/finalization  subroutines 
. Data  block  update  subroutines 
. Data  block  retrieval  subroutines 
Specific  subroutines  and  the  functions  they  perform  are  in- 
dicated in  the  following  list.  Details  regarding  subroutine 
operation  and  calling  formats  are  discussed  in  Section  III. 

Data  Base  Initial ization/Final  ization  Subroutines 

SBUFF  Defines  a buffer  for  use  in  retrieval  and  up- 
date operations. 

ILFN  Opens  and  initializes  a CDMS  data  base  file 

FLFN  Closes  and  finalizes  the  current  data  base  file 
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Data  Block  Update  Subroutines 


DEFINE 

CHANGE 

ADDO 

CHANGO 

ADDU 

DELETE 


DELETE 

MODBN 

PFNIN 

Data  Block 

FETCH 


Creates  a data  block 

Adds  or  changes  the  data  value(s)  for  either 
a single-valued  or  array  element  that  is  not  a 
member  of  a repeating  group 
Adds  an  occurrence  to  a repeating  group 
Changes  an  occurrence  of  a repeating  group 
Adds  a locally  defined  element  and  its  value(s) 
to  a data  block 

Deletes  the  data  value(s)  for  either  a single- 
valued or  an  array  element  that  is  not  a member 
of  a repeating  group;  can  also  delete  one  or  all 
occurrences  of  a repeating  group  element,  and  one 
or  all  occurrences  of  a repeating  group 
Deletes  a data  block 
Changes  the  name  of  a data  block 

Stores  the  name  of  the  file  referenced  by  a cross- 
file pointer  and  completes  the  definition  of  that 
pointer  by  inserting  an  index  that  indicates  where 
the  file  name  is  stored. 

Retrieval  Subroutines 

Retrieves  the  data  value(s)  for  either  a single- 
valued or  an  array  element  that  is  not  a member 
of  a repeating  group;  can  also  retrieve  one  or 
all  occurrences  of  a repeating  group  element,  and 
one  or  all  occurrences  of  a repeating  group. 
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FETCHN  Retrieves  the  data  value{s)  for  a set  of  non- 
repeating group  elements. 

FETCHR  Retrieves  the  data  value(s)  for  a set  of  repeating 
group  elements. 

QUERY  Searches  inverted  lists  for  the  names  of  those 
data  blocks  that  satisfy  certain  user-specified 
conditions. 

FETCHC  Retrieves  the  data  value(s)  for  a specific  re- 
peating group  occurrence,  according  to  an 
identifier  provided  by  subroutine  QUERY. 

NOCC  Determines  the  number  of  occurrences  within  a 

given  repeating  group 

INPFN  Retrieves  the  name  of  the  file  referenced  by  a 

cross-file  pointer,  using  an  index  that  indicates 
where  the  file  name  is  stored 


B.  DATA  BASE  PROCESSING 

The  initialization/finalization  subroutines  of  the  CDMS 
host  language  interface  are  used  to  define  a buffer  that  will 
be  used  for  retrieving  and  updating  data  base  information, 
to  open  and  initialize  the  data  base  for  storage  and  access, 
and  to  close  and  finalize  the  data  base  when  its  current  use 
is  ended  or  another  file  is  to  be  used  for  processing.  Any 
number  of  data  base  files  may  be  established  for  use  by  the 
host  language  subroutines  subject  to  the  conventions  and 
limitations  of  the  SCOPE  operating  system. 
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Subroutine  SBUFF  defines  a buffer  which  in  reality  is  a 
user-supplied  array.  The  buffer  may  contain  as  many  as  20 
data  blocks  at  one  time.  The  programmer  need  not  reference 
this  area,  since  the  host  language  subroutines  will  perform 
whatever  buffer  management  is  required. 

Subroutine  ILFN  is  used  to  open  a data  base  file.  Files 
will  exist  on  those  permanent  file  devices  recognized  by  SCOPE. 
When  data  processing  is  complete  or  when  another  data  base  file 
is  to  be  used,  subroutine  FLFN  is  called  to  close  and  finalize 
the  current  file.  When  the  file  is  closed,  it  is  logically  dis- 
connected; further  processing  cannot  take  place  until  a call  to 
ILFN  is  issued. 

CDMS  data  base  files  are  processed  as  random  files  and  are 
supported  by  the  COMRADE  Data  Storage  Facility  (CDSF). 

C.  DATA  BLOCK  UPDATE  AND  RETRIEVAL 

The  storage  and  retrieval  of  data  blocks  is  managed  by  the 
host  language  interface  software  and  its  underlying  primitives. 
When  a data  block  is  created,  it  is  given  a name.  A directory 
of  the  names  of  all  blocks  on  a file  is  kept,  and  includes  the 
disk  addresses  on  the  file  where  each  of  the  blocks  may  be 
found.  The  CDSF  is  responsible  for  directory  handling  and 
disk  space  allocation. 

After  block-types  have  been  defined  using  the  DEFINE  module 
of  the  CDMS  conversational  interface^,  the  host  language  sub- 
routines can  be  used  to  create,  update,  and  retrieve  data 
blocks  and  their  contents.  These  subroutines  allow  named 
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data  elements  to  be  processed  symbolically  or  logically,  without 
regard  to  internal  data  block  structure  or  the  location  of  data 
within  a block.  The  named  elements  can  be  of  real,  integer, 
character,  or  pointer  type  data,  and  can  be  either  single- 
valued elements  or  arrays.  Single-valued  elements  can  be 
inverted  and  used  as  keys  in  retrieval  requests;  pointer- 
type  elements  can  be  used  to  form  relationships  among  blocks 
within  the  same  or  different  files.  Sets  of  elements  can  be 
grouped  together  under  a group  name  with  occurrences  of  the 
group  repeated  as  often  as  needed  (i.e.,  repeating  groups  of 
data ) . 

D.  AUXILIARY  FACILITIES 

The  host  language  subroutines  are  resident  on  two  libraries 
that  are  shared  by  the  CDMS  user  community.  Operational  pro- 
cedures relative  to  use  of  the  libraries  are  discussed  in 
Appendixes  D and  F.  These  shared  libraries  also  contain  three 
sets  of  utility  subroutines  which  have  been  found  to  be  quite 
useful  to  programmers.  These  subroutines--discussed  in 
Appendixes  E,  G and  H--allow  an  executing  program  to  perform  a 
variety  of  functions,  including  bit  manipulations,  alphanumeric 
data  manipulations  and  conversions,  and  permanent  file 
management  for  SCOPE  and  CPFMS  files. 
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III.  DETAILED  DESCRIPTION  OF  THE  HOST  ' ANGUAGE  INTERFACE 

J 

.1 

The  following  detailed  descriptions  of  the  19  user-callable  i 

1 

CDMS  host  language  subroutines  observe  certain  conventions. 

i 

In  the  calling  formats  for  the  subroutines,  the  user-supplied  , 

1 

parameters  have  been  underlined  and  the  parameters  returned  ; 

to  the  calling  program  have  been  overlined.  Parameters  fre-  | 

quently  used  by  the  subroutines  are  indicated  and  are  followed  i 

a 

by  a list  of  standard  error  codes  returned  ‘-.o  the  user  by  the  j 

host  language  interface  software.  \ 

A.  FREQUENTLY  USED  PARAMETERS 

Eight  parameters  are  used  frequently  by  the  CDMS  host 
language  subroutines: 

ICODE  An  error  code  returned  by  a subroutine.  In  a 
few  instances,  ICODE  is  also  used  as  an  input 
parameter . 

BN  The  name  of  a data  block  on  which  an  update  or 

retrieval  operation  is  to  be  performed.  BN  may 
contain  as  many  as  eight  characters,  left- 
justified,  H format. 

SBN  The  name  or  number  of  a subblock  containing  the 

data  element  or  repeating  group  on  which  an  update  :: 

f 

or  retrieval  operation  is  to  be  performed.  SBN  i 

f 

(set  to  zero  if  unused)  is  an  optional  parameter  | 

which  can  reduce  the  time  necessary  to  process  the 
user's  request.  SBN  may  contain  either  characters  1 

(as  many  as  eight,  lef t- j ust  if ied  , H format),  or  I 
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RGN 


RGO 


EN 


DATA 


LENGTH 


an  integer  in  the  range  1-8,  inclusive. 

The  name  of  a repeating  group  on  which  the  update 
or  retrieval  operation  is  to  be  performed.  RGN 
may  contain  as  many  as  eight  characters,  left- 
justified,  H format;  if  unused,  RGN  should  be 
set  at  zero. 

The  number  of  the  repeating  group  occurrence 
involved  in  the  update  or  retrieval  operation. 

RGO  should  contain  an  integer  greater  than  or 
equal  to  zero;  a zero  value  for  RGO  indicates 
either  "all  occurrences"  or  "not  applicable" 
depending  on  the  use  of  the  subroutine.  In 
a few  instances,  RGO  is  an  output  parameter 
indicating  the  total  number  of  occurrences 
contained  in  the  repeating  group. 

The  name  of  the  data  element  on  which  the  update 
or  retrieval  operation  is  to  be  performed.  EN 
may  contain  as  many  as  eight  characters,  left- 
justified,  H format.  If  unused,  EN  should  be  set 
to  zero. 

As  an  input  parameter,  an  array  of  new  data  values. 
As  an  output  parameter,  an  array  of  retrieved  in- 
formation. The  format  of  DATA  differs  somewhat 
from  subroutine  to  subroutine;  details  are  provided 
in  the  individual  subroutine  descriptions. 

For  update  operations,  an  integer  specifying  the 
length  of  the  DATA  array.  For  retrieval  operations. 
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LENGTH  is  both  an  input  ar.u  output  parameter.  As 
an  input  parameter,  LENGTH  indicates  the  maximum 
number  of  values  which  may  be  retrieved  and  placed 
into  DATA;  on  output,  LENGTH  specifies  the  number 
of  values  actually  retrieved. 


B.  STANDARD  ERROR  CODES 

Code  No.  Interpretation 


0 

No  erro 

r detected 

1 

No  data 

base  initialized 

2 

Illegal 

data  block  specif 

icat ion 

3 

No  valu 

e loaded  for  data 

element 

4 

Illegal 

subblock  specific 

at  ion 

5 

I 1 legal 

repeating  group  s 

pecif icat 

ion 

6 

Illegal 

data  element  spec 

if ication 

7 

Subscr i 

pt  specification  e 

xceeds  ar 

r ay  s 

8 

Interna 

1 error  (may  be  du 

e to  bad 

data 

block ) 

9 

Illegal 

block  type  specif 

ication 

10 

Data  bl 

ock  already  exists 

11 

I 1 legal 

buffer  size 

12 

Working 

area  too  small  fo 

r those  values 

which  a 

re  to  be  retrieved 

; no  values 

retrieved 

13  Unable  to  open  file 

14  No  buffer  initialized,  or  buffer  too  small 
for  processing  inverted  elements 

15  Unable  to  finalize  data  base  file 

16  Illegal  data  type 

17  Illegal  logical  unit  number 

18  Syntax  error  in  the  array  containing  the 
retrieval  criteria  for  subroutine  QUERY, 
or  the  array  is  too  long 

19  An  entry  containing  a block  name  and  the 
related  repeating  group  occurrence  ident- 
ifiers is  too  large  to  be  written  to  the 
hit  file;  file  unloaded  (the  user  receiving 
this  error  may  wish  to  use  the  COMRADE 
Data  Storage  Facility  Subroutine  CULL) 

20  Illegal  index  into  the  cross-file  reference 

table 

21  Cross-file  reference  table  full 


30 


C.  DATA  BASE  INITIALIZATION/FINALIZATION  SUBROUTINES 


1.  SBUFF 

SBUFF( iCODE,  BUFF,  SIZE) 

SBUFF  defines  the  data  buffer  to  be  used  by  the  CDMS  host 
language  interface  subroutines.  A buffer  must  be  defined 
before  a CDMS  data  base  file  can  be  initialized  and  processed. 
If  a previously  defined  buffer  has  been  in  use,  it  will  be 
emptied  and  made  available  to  the  calling  program. 

Parameters : 

ICODE  Standard  error  code. 

BUFF  Name  of  the  buffer  space  (as  declared  in  a FORTRAN 

DIMENSION  statement^^)  . 

SIZE  Size  of  buffer;  a minimum  of  129  words  is  re- 

quired unless  inverted  lists,  which  must  have 
a minimum  of  1025  words,  are  to  be  accessed. 

Example : 


DIMENSION  BUFF  (1025) 


CALL  SBUFF  (ICODE,  BUFF,  1025) 
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2.  ILFN 


ILFN  (ICODE,  LFN,  INV) 

ILFN  opens  and  initializes  the  CDMS  data  base  file. 
Parameters : 

ICODE  Standard  error  code. 

LFN  SCOPE  logical  file  name  ( lef t- j ust i f ied , H format) 

of  the  data  base  file  to  be  opened  and  initialized. 
MR  Multi-read  indicator: 

= 0 Open  file  for  read  and  write  processing 
=/  0 Open  file  for  read  processing  only 
INV  Inversion  indicator: 

= 0 By-pass  all  inverted  list  transactions 

^ 0 Construct  an  inverted  list  transaction 

file  which  will  be  processed  when  the 
data  base  file  is  finalized. 

3.  FLFN 

FLFN  ( ICODE , LFN) 

FLFN  processes  the  file  (if  one  exists)  of  inverted  list 
transactions;  rewrites  the  data  base  file's  directory  and  cross- 
file reference  table  (if  they  have  been  modified);  and  closes 
and  finalizes  the  data  base  file. 

Parameters : 

ICODE  Standard  error  code. 

LFN  SCOPE  logical  file  name  ( le f t- j ust  i f ied  , H format) 

of  the  data  base  file  to  be  closed  and  finalized. 
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D.  DATA  BLOCK  UPDATE  SUBROUTINES 

1.  DEFINE 

DEFINB(  ICODE,  BT) 

DEFINE  creates  a data  block  for  a given  block  type. 
Parameters : 

ICODE  Standard  error  code. 

BN  Data  block  name  for  the  block  to  be  defined. 

BT  Block  type  name;  block-type  definitions  are 

created  by  way  of  the  CDMS  conversational  inter- 
face DEFINE  module.^ 

Example ; 

Suppose  a user  wishes  to  define  the  block  JONES  (to  contain 
personal  information  about  Tom  Jones)  for  the  block  type 
PERSONAL  (defined  previously  via  the  DEFINE  module).  The  user 
might  code 

CALL  DEFINE  (ICODE,  5HJ0NES,  8HPERSONAL) 

2.  CHANGE 

CHANGE  ( IJODE . BN,  SBN , EN , DATA) 

CHANGE  adds  or  changes  the  data  value(s)  for  either  a 
single-valued  element  or  an  array  element;  in  either  case, 
the  element  must  not  be  a member  of  a repeating  group. 
Parameters : 

ICODE  Both  an  input  and  an  output  parameter.  If  a 
single-valued  element  is  to  be  changed,  then 
ICODE  is  ignored  as  an  input  parameter.  If  an 
entire  array  is  to  be  changed,  then  ICODE  must 
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be  set  to  ?ero;  if  a specific  value  in  an  array 
is  to  be  changed,  ICODE  must  be  non-zero.  As  an 
output  parameter,  ICODE  is  a standard  error  code. 

BN  Data  block  name 

SBN  Subblock  name  or  number 

EN  Data  element  name 

DATA  The  value(s)  to  be  added  or  inserted  for  the 

element  EN.  If  EN  is  a single-valued  element, 
then  DATA  simply  contains  the  new  value.  If 
EN  is  an  array  and  if  a specific  value  of  EN 
is  to  be  changed,  then  DATA  is  a two-word  array — 
the  first  word  containing  the  subscript  of  the 
location  within  EN  that  is  to  be  changed,  and 
the  second  word  containing  the  new  value.  If 
an  array  of  new  values  is  to  be  added  or  inserted 
for  the  array  EN , the  first  word  of  DATA  must 
contain  the  number  of  values  in  the  new  array 
(i.e.,  the  dimension)  and  subsequent  words  will 
contain  the  values. 

Example : 

Suppose  a data  block  JONES  (a  block  containing  personal  data 
about  Tom  Jones)  is  of  block  type  PERSONAL  and  contains  the  two 


subblocks  SELF  and  FAMILY.  Suppose  further  that  data  elements 
HOBBIES  (an  array)  and  PHONE  (home  telephone  number;  a single- 
valued element)  are  included  in  subblock  SELF,  and  that  the 
element  CHILDREN  is  included  in  subblock  FAMILY.  Assume  that 


none  of  these  elements  are  members  of  a repeating  group  and 
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that  the  data  base  must  be  updated  to  account  for  the  following: 

(a)  MR.  Jones  has  a different  home  phone  number,  793-5971; 

(b)  MR.  Jones  third  hobby  should  read  GOLF  instead  of  GULF; 
and 

(c)  The  Jones  family  now  includes  two  children,  DAVID  and 
SUSAN. 

To  effect  these  changes,  the  user  might  code  as  follows: 

INTEGER  DATA  ( 3 ) 

C SET  UP  PHONE  NUMBER  CHANGE 
BN  = 5HJ0NES 
SBN  = 4HSELF 
EN  = 5HPHONE 
NUMBER  = 8H793-5971 

CALL  CHANGE  (ICODE,  BN,  SBN,  EN , NUMBER) 

IF  {ICODE. NE.O)  STOP  10 
C SET  UP  HOBBY  CHANGE 
ICODE  = 1 
EN  = 7HHOBBIES 
DATA (1 ) = 3 
DATA(2)  = 4HGOLF 

CALL  CHANGE  (ICODE,  BN,  SBN,  EN , DATA) 

IF  (ICODE. NE.O)  STOP  20 
C SET  UP  CHILDREN  CHANGE 

L 
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SBN  = 6HFAMILY 


EN  = 8HCHILDREN 


DATA(l) 

= 2 

DATA ( 2 ) 

= 5HDAVID 

DATA( 3) 

= 5HSUSAN 

ICODE  = 

0 

CALL  CHANGE  (ICODE,  BN,  SBN,  EN , DATA) 

IF  (ICODE. NE.O)  STOP  30 

Note  that  the  user  could  have  saved  several  lines  of  code  by 
entering  BN,  SBN,  and  EN  as  constants  in  the  calling  sequences. 

3.  ADDO 

ADDO  { ICODA,  BN,  SBN,  RGN , DATA,  LENGTH) 

ADDO  adds  one  occurrence  to  a particular  repeating  group. 
The  new  occurrence  is  always  added  at  the  end,  thus  becoming 
the  last  occurrence  of  the  repeating  group. 

Parameters : 

ICODA  An  array  of  error  codes,  one  array  location  for 

each  repeating  group  member  whose  name  appears  in 
the  DATA  array.  If  each  location  of  ICODA  is  zero 
on  return  from  ADDO,  then  the  data  values  (con- 
tained in  DATA)  will  have  been  successfully  added 
as  the  last  occurrence  for  RGN.  If  location 
ICODA(i)  is  set  to  6 by  ADDO,  the  ith  element 
could  not  be  processed  and  no  new  occurrence 
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will  have  been  added  to  repeating  group  RGN. 

Other  errors  occurring  in  ADDO  will  cause  ICODA(l) 
to  be  set  to  one  of  the  other  standard  error  codes. 

BN  Data  block  name 

SBN  Subblock  name  or  number 

RGN  Name  of  the  repeating  group  to  which  the 

occurrence  is  to  be  added. 

DATA  An  array  comprising  consecutive  entries  of  two 

or  more  computer  words  each,  one  entry  for  each 
RGN  member  that  is  to  be  processed  by  the  current 
call  to  ADDO.  The  first  word  of  each  entry  must 
be  the  member  name  (H  format,  lef t- j ust  i f ied  ) . 

For  a single-valued  element,  the  second  word 
of  the  entry  must  be  the  data  value.  For  an 
array  element,  the  second  word  must  be  the 
dimension,  n,  of  the  array;  the  next  n words 
in  the  entry  must  be  the  array  values. 

LENGTH  The  total  number  of  words  in  DATA  to  be  processed. 
The  user  should  dimension  DATA  for  at  least 
LENGTH  locations. 

Example : 

Suppose  a block  JONES  (a  block  containing  personal  data 
about  Tom  Jones)  is  of  block  type  PERSONAL  and  contains  the 
elements  TITLE  (a  single-valued  element),  SALARY  (an  array  of 
salary  information),  and  COWORKER  (an  array  of  pointers  in- 
dicating persons  who  have  worked  with  Tom  Jones).  Suppose 
further  that  these  three  elements  are  members  of  the  repeating 
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group  JOBS,  and 
account  for  the 
job.  To  effect 


that  the  data  base  must  now  be  updated  to 
fact  that  Mr.  Jones  has  just  begun  his  third 
this  change  the  user  might  code  as  follows: 


DIMENSION  ICODA  (3),  IDATA  (12),  DATA  (12) 
EQUIVALENCE  (DATA,  IDATA) 


C SET  UP  CONTENTS  OF  ARRAY 
C SET  UP  TITLE  ENTRY 
DATA  (1)  = 5HTITLE 
DATA  (2)  = 7HCHEMIST 
C SET  UP  SALARY  ENTRY 


DATA 

(3) 

= 6HSALARY 

IDATA 

(4) 

= 1 

DATA 

(5) 

= 12000.0 

SET  UP 

COWORKER  ENTRY 

DATA 

(6) 

= 8HCOWORKER 

IDATA 

(7) 

= 5 

DATA 

(8) 

= 5HBROWN 

DATA 

(9) 

= 8HGOLDBERG 

DATA 

(10) 

= 5HADAMS 

DATA 

(11) 

= 6HNEWTON 

DATA 

(12) 

= 6HNELSON 

CALL  ADDO  (ICODA,  5HJONES,  1, 


4HJOBS,  DATA,  12) 


4.  CHANGO 


CHANGO  ( ICODA,  BN,  SBN,  RGN,  RGO,  DATA,  LENGTH) 

CHANGO  changes  one  occurrence  of  a specific  repeating 
group.  The  member  elements  to  be  changed  may  be  either  single- 
valued elements  or  arrays.  CHANGO  may  be  used  to  add  or  replace 
a set  of  array  values,  or  to  replace  a specific  value  in  an 
array. 

Parameters : 

ICODA  An  array  of  error  codes,  one  array  location  for 
each  repeating  group  member  whose  name  appears 
in  the  DATA  array.  As  an  output  parameter,  if 
each  location  of  ICODA  is  set  to  zero,  then  all 
data  values  (contained  in  DATA)  will  have  been 
successfully  inserted  into  occurrence  RGO.  If 
location  ICODA(i)  is  set  to  six  by  CHANGO,  then 
the  ith  element  could  not  be  processed  and  no 
values  will  have  been  inserted  into  occurrence 
RGO  for  any  element.  If  ICODA(i)  is  set  to  seven 
by  CHANGO,  the  value  for  the  ith  element  will  not 
have  been  inserted  into  occurrence  RGO.  Other 
CHANGO  errors  will  cause  ICODA(l)  to  be  set  to 
one  of  the  other  standard  error  codes.  As  an 
input  parameter,  ICODA  signifies  the  type  of 
processing  for  arrays.  If  the  ith  element  named 
in  DATA  is  an  array,  location  ICODA(i)  will  be 
examined.  If  ICODA(i)  equals  zero,  CHANGO  assumes 
that  all  current  array  values  are  to  be  replaced, 
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and  that  a new  set  of  values  is  to  be  inserted 


1 


into  the  occurrence.  A non-zero  ICODA(i)  3 

indicates  that  a specific  array  value  is  to  j 

be  replaced.  ] 

BN  Data  block  name 

SBN  Subblock  name  or  number 

RGN  Repeating  group  name 

RGO  Repeating  group  occurrence  number  (a  positive 

integer ) 

DATA  An  array  comprising  consecutive  entries  of  two  or 
more  computer  words  each,  one  entry  for  each  RGN 
member  that  is  to  be  processed  by  the  current 
call  to  CHANGO.  The  first  word  of  each  entry 
must  be  the  member  name  (H  format,  lef t- j ust if ied ) . 

For  a single-valued  element,  the  second  word  in 
the  entry  must  be  the  data  value.  For  an  array 
element,  the  second  word  must  be  either  the 
dimension  of  the  new  array,  or  the  subscript 
of  the  specific  value  that  is  to  be  replaced 
in  the  existing  array;  the  next  word(s)  in  the 
entry  must  be  the  array  value(s). 

LENGTH  The  total  number  of  words  in  DATA  to  be  processed. 

The  user  should  dimension  DATA  for  at  least  LENGTH 
locations . 

Example : 

Suppose  a block  JONES  (a  block  containing  personal  data  about 
Tom  Jones)  is  of  block  type  PERSONAL  and  contains  the  elements 
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TITLE  (a  single-valued  element),  SALARY  (an  array  of  real 
values),  and  COWORKER  (an  array  of  pointers).  Suppose 
further  that  the  three  elements  are  members  of  repeating 
group  JOBS,  that  Mr.  Jones'  position  title  in  occurrence  4 
of  JOBS  is  spelled  CHMEIST  instead  of  CHEMIST,  and  that  Mr. 
Jones'  salary  history  and  co-worker  roster  must  be  updated 
with  the  values  12,000.0,  12,850.0,  and  SMITH.  To  effect  these 
cnanges  the  user  might  code  as  follows: 


DIMENSION  DATA  (10),  IDATA(IO),  ICODA(3) 
EQUIVALENCE  (DATA,  IDATA) 


C 

C 


C 


C 

C 

C 


SET  UP 

CONTENTS  OF  DATA 

SET  UP 

TITLE 

ENTRY 

DATA 

(1)  = 

5HTITLE 

DATA 

(2)  = 

7HCHEMIST 

SET  UP 

SALARY 

ENTRY 

DATA 

(3)  = 

6HSALARY 

DATA 

(4)  = 

2 

DATA 

(5)  = 

12000.0 

DATA 

(6)  = 

12850.0 

SET  UP 

COWORKER  ENTRY 

DATA 

(7)  = 

8HCOWORKER 

SET  UP 

SUBSCRIPT  FOR  LOCATION  WITHIN  COWORKER 

THAT  IS 

TO  BE 

REPLACED 
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IDATA  (8)  =3 


DATA  (9)  = 5HSMITH 
C SET  UP  OTHER  VALUES  AS  REQUIRED 
ISBN  = 1 
ICODA  (2)  =0 
ICODA  (3)  =1 

CALL  CHANGO  (ICODA,  5HJONES,  ISBN,  4HJOBS,  4,  DATA,  9) 


5.  ADDU 

ADDU  ( ICODE,  BN,  SBN,  EN,  IV,  DATA) 

ADDU  allows  a user  to  add  a locally  defined  element  to  a 
data  block,  and  to  also  add  the  value(s)  for  that  element. 
Parameters : 

ICODE  As  an  input  parameter,  ICODE  indicates  the  data 
type  and  array  status  of  the  new  element,  and 
must  be  equal  to  one  of  the  following: 

0 Alpha  single-valued  element 

1 Integer  single-valued  element 

2 Real  single-valued  element 

3 Pointer  single-valued  element 

10  Alpha  array  element 

11  Integer  array  element 

12  Real  array  element 

13  Pointer  array  element 

14  Text  element 
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As  an  output  parameter,  ICODE  is  a standard  error 
code . 


BN  Data  block  name 

SBN  Subblock  name  or  number 

EN  Data  element  name;  must  be  unique  for  this  data 

block 

IV  Inversion  indicator: 

= 0 Consider  the  element  to  be  non-inverted 
^ 0 Consider  the  element  to  be  inverted 

DATA  The  value(s)  to  be  added  for  element  EN.  If  EN 
is  a single-valued  element,  DATA  will  simply 
contain  the  value.  If  EN  is  an  array,  the  first 
word  of  DATA  will  contain  the  number  of  values 
in  the  array  while  subsequent  words  will  contain 
the  values. 

Example : 

Suppose  an  employee  named  Tom  Jones  has  a unique  medical 
history.  In  the  event  of  an  emergency,  it  is  necessary  that 
Mr.  Jones'  personnel  record  (in  this  example,  a data  block  named 
JONES)  contain  several  vital  pieces  of  information.  To  effect 
insertion  of  values  for  the  elements  BLOODTYP  (a  single- 
valued element)  and  ALLEGERY  (an  array),  the  user  might  code 
as  follows: 

EN  = 8HBL00DTYP 

DATA  (1)  = 6HAB  NEG 
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ICODE  = 0 


CALL  ADDU  (ICODE,  5H JONES,  1,  EN , 0,  DATA) 
IF  (ICODE. NE.O)  STOP  10 
EN  = 7HALLERGY 
DATA(l)  = 3 

DATA(2)  = lOHPENICILLIN 
DATA(3)  = 7HASPIRIN 
DATA(4)  = 9HNOVACAINE 
ICODE  = 10 

CALL  ADDU  ( ICODE , 5H JONES , 1,  EN , 0,  DATA) 
IF  (ICODE. NE.O)  STOP  20 


6.  DELETE 

DELETE  ( ICODE,  BN,  S^,  R^,  R^,  ^) 

DELETE  deletes  elements  (either  single-valued  or  array) 
a data  block.  The  subroutine  can  delete  a non-repeating  group 
element,  or  it  can  delete  one  or  all  occurrences  of  a repeating 
group  element.  If  required,  one  occurrence  or  all  occurrences 
of  a repeating  group  can  be  deleted. 

Parameters : 

ICODE  Standard  error  code 

BN  Data  block  name 

SBN  Subblock  name  or  number 

RGN  Repeating  group  name;  used  only  when  a specific 

occurrence  or  all  occurrences  are  to  be  deleted 
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RGO 


EN 


Examples 
Use  of 
following 


DELETE  Processing  Actions  Parameter  Value 

RGN  RGO  EN 


1. 

all  occurrences  of  a 

repeating 

0 

0 

repeating  group 

group  name 

2. 

ith  occurrence  of  a 

repeating 

repeating  group 

group  name 

i 

0 

3 . 

all  occurrences  of  a 
repeating  group 

ignored 

0 

element 

element 

name 

4. 

ith  occurrence  of  a 
repeating  group 

ignored 

i 

element 

element 

name 

5. 

non-repeating  group 

element 

element 

ignored 

ignored 

name 

Repeating  group  occurrence  number  (ignored  when 
a non-repeating  group  element  is  to  be  deleted): 

= 0 Process  all  occurrences 

= i,  where  i >0  Process  ith  occurrence 

When  one  or  all  occurrences  of  an  entire  repeating 

group  are  to  be  deleted,  EN  must  be  set  to  zero. 

Otherwise,  it  is  used  to  indicate  the  name  of  the 

data  element  to  be  deleted. 

parameters  RGN,  RGO,  and  EN  is  summarized  in  the 
table  and  calling  sequences: 


(1) 

CALL 

DELETE 

( ICODE, 

5HJONES, 

8HINDIVIDL, 

0, 

0,  6HWEIGHT) 

(2) 

CALL 

DELETE 

{ ICODE, 

5HJONES, 

8HINDIVIDL, 

4HJOBS,  0, 

0) 

(3) 

CALL 

DELETE 

( ICODE, 

5HJONES, 

8HINDIVIDL, 

0, 

2,  4HYEAR) 

(4) 

CALL 

DELETE 

( ICODE, 

5HJONES, 

8HINDIVIDL, 

4HJOBS,  2, 

0) 
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(5)  CALL  DELETE  (ICODE,  5HJONES,  8HINDIVIDL,  0,  0,  4HYEAR) 


In  (1),  DELETE  is  called  to  delete  the  value  for  the  element 
WEIGHT  from  the  block  JONES  (assume  WEIGHT  to  be  a non-repeating 
group  element).  In  (2),  all  occurrences  of  the  repeating  group 
JOBS  are  to  be  deleted.  In  (3),  the  element  YEAR  is  to  be 
deleted  from  occurrence  2 of  JOBS  (assume  YEAR  to  be  a member 
of  JOBS).  In  (4),  the  entire  second  occurrence  of  JOBS  is  to 
be  deleted.  Finally,  in  (5),  the  element  YEAR  is  to  be  deleted 
from  all  occurrences  of  the  repeating  group  JOBS. 

7.  DELETB 

DELETB( ICODE,  BN) 

DELETB  deletes  a data  block.  Further  reference  to  the  block 
is  thus  impossible. 

Parameters : 

ICODE  Standard  error  code 

BN  Data  block  name 

Example : 

To  delete  a data  block  JONES,  the  user  might  code 
CALL  DELETB  (ICODE,  5HJONES) 

8 . MODBN 

MODBN  ( ICODE,  OLDBN , NEWBN) 

MODBN  allows  the  user  to  change  the  name  of  a data  block. 
Parameters : 

ICODE  Standard  error  code 

OLDBN  Data  block  name  to  be  changed 

NEWBN  New  data  block  name 
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PFNIN 


PFNIN  (ICODE,  DATA,  PFN,  ID,  FILTYP) 

PFNIN  stores  the  name  of  the  permanent  file  referenceo  by 
a cross-file  pointer,  and  then  completes  the  definition  of  that 
pointer  by  inserting  a cross-file  reference  table  index  in- 
dicating where  the  file  name  has  been  stored.  The  index  is 
used  by  subroutine  INPFN  during  cross-file  pointer  processing. 

Parameters : 

ICODE  Standard  error  code 

DATA  A variable  containing  a pointer  of  as  many  as  eight 

characters,  left-justif ied , H format.  Upon  com- 
pletion of  PFNIN,  DATA  will  also  contain  a cross- 
file reference  table  index  in  the  12  right-most 
bit  positions. 

PFN  Name  of  the  permanent  file  containing  the  data 

block  identified  by  the  pointer  in  DATA.  If  a 
SCOPE  file,  PFN  must  contain  the  permanent  file 
name  of  as  many  as  40  characters.  If  a CPFMS 
file,  PFN  must  contain  the  level-3  name  of  as 
many  as  eight  characters,  left- justified , H format. 

ID  For  a SCOPE  file,  the  four-character  ID;  for  a 

CPFMS  file,  the  level-4  name  of  as  many  as  eight 
characters,  lef t- j ust i f ied , H format. 

FILTYP  File  type  code: 

= 0 SCOPE  file 
= 1 CPFMS  file 
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DATA  BLOCK  RETRIEVAL  SUBROUTINES 


1.  FETCH 

FETCH  ( ICODE,  S^,  RGN , R^,  DATA,  LENGTH) 

FETCH  can  retrieve  any  data  element  (either  single-valued 
or  array)  whether  or  not  the  element  is  a member  of  a repeating 
group.  If  in  a repeating  group,  either  a specific  occurrence 
of  the  element  or  all  occurrences  of  the  element  may  be  re- 
trieved. Moreover,  one  occurrence  or  all  occurrences  of  a 
repeating  group  may  be  retrieved. 

Parameters ; 

ICODE  Standard  error  code 

BN  Data  block  name 

SBN  Subblock  name  or  number 

RGN  Repeating  group  name;  used  only  when  a specific 

occurrence  or  all  occurrences  are  to  be  retrieved 
RGO  As  an  input  parameter,  a repeating  group  occurrence 

number : 

= 0 Process  all  occurrences 
= i where  i ’’  0 Process  ith  occurrence 
As  an  output  parameter,  the  total  number  of 
occurrences  in  the  repeating  group.  RGO  is  ignored 
when  a non-repeating  group  element  is  to  be  retrieved. 
EN  When  one  occurrence  or  all  occurrences  of  an  entire 

repeating  group  are  to  be  retrieved,  EN  must  be  set 
to  zero.  Otherwise,  the  name  of  the  data  element 
to  be  retrieved. 


1 


I 


f 


f 


I 

i 


48 


DATA 


\ 

[ 

f 

! 

I 


I 


I 


f 
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A user-supplied  work  space  used  to  store  the 
value(s)  retrieved  by  FETCH.  The  structure  of 
DATA  is  dependent  upon  the  type  of  processing 
action  performed  by  FETCH.  The  following  lists 
summarize  FETCH  processing  actions  and  potential 
organizations  of  the  DATA  array. 

FETCH  Processing  Actions: 

(1)  A non-repeating  group  single-valued  element 
or  a specific  occurrence  of  a single-valued 
repeating  group  element 

(2)  A non-repeating  array  element  or  a specific 
occurrence  of  a repeating  group  array  element 

(3)  All  occurrences  of  a repeating  group  element 

(4)  One  occurrence  of  a repeating  group 

(5)  All  occurrences  of  a repeating  group 

DATA  organizations  (keyed  to  processing  actions): 

(1)  Contains  the  value  of  the  single-valued  element 

(2)  Contains  the  dimension,  n,  of  the  array  in 
the  first  word  and  the  array  values  in  the 
subsequent  n words 

(3)  Contains  consecutive  entries,  one  for  each 
repeating  group  occurrence.  If  the  element 
is  single-valued,  each  entry  will  contain 
either  (a)  a value,  or  (b)  an  octal  pattern 
of  76767676767676767676  indicating  that  no 
value  has  been  loaded  for  this  occurrence. 

If  the  element  is  an  array,  each  entry  will 
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contain  either  (a)  a dimension  word  followed 


by  «-he  array  values,  or  (b)  a zero  indicating 
that  no  values  have  been  loaded  for  this 
occurrence . 

(4)  Contains  consecutive  entries,  one  for  each 
member  of  the  repeating  group.  The  entries 
are  ordered  in  the  same  way  that  the  repeating 
group  elements  are  defined  in  the  block-type 
definition.  The  entry  for  a single-valued 
element  will  be  either  a value,  or  an  octal 
pattern  of  76767676767676767676  signifying 

no  value  has  been  loaded  for  this  occurrence. 
The  entry  for  an  array  will  be  either  a 
dimension  word  followed  by  the  array  values, 
or  a zero  indicating  no  values  have  been 
loaded  for  the  occurrence. 

(5)  Contains  sets  of  consecutive  entries  as 
described  in  DATA  organization  (4).  The 
sets  themselves  are  consecutive  and  are 
sequenced  according  to  the  repeating  group 
occurrence  number. 

LENGTH  As  an  input  parameter,  the  total  number  of  words 

in  DATA  that  can  be  used  for  retrieved  information; 
the  user  must  dimension  DATA  to  have  at  least 
LENGTH  words.  As  an  output  parameter,  the  number 
of  words  in  DATA  which  actually  contain  retrieved 
information. 
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Example ; 


A user  might  code 

DIMENSION  DATA  ( 50 ) 

LENGTH  = 50 
IRGO  = 0 

CALL  FETCH  (ICODE,  5HJONES,  6HFAMILY,  8HMARRIAGE,  IRGO,  0, 
DATA,  LENGTH) 

Execution  of  this  code  results  in  the  retrieval  of  all  occurrences 
of  the  repeating  group  MARRIAGE  from  the  block  JONES.  If  the 
block-type  definition  for  MARRIAGE  comprises  the  elements 
WIFE  (a  single-valued  element),  YEARM  (also  a single-valued 
element),  and  CHILDREN  (an  array),  then  DATA  will  appear  as 
follows : 

Word 

1 ELLEN 

2 1885 

3 3 

4 MARGARET 

5 SUSAN 

6 ERIN 

7 CAROLYN 

8 1915 

9 0 

Two  occurrences,  representing  marriages  to  Ellen  and  Carolyn, 
have  been  retrieved;  the  second  marriage  resulted  in  no  children 
as  indicated  by  the  zero.  The  parameter  LENGTH  would  contain 
the  value  9. 

L 
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2. 


FETCHN 


FETCHN  { fCODA,  SBN , ENA,  DATA,  LENGTH) 

FETCHN  retrieves  data  values  for  a set  of  non-repeating 
group  elements;  the  set  may  consist  of  single-valued  elements 
and  array  elements. 

Parameters : 

ICODA  An  array  of  error  codes,  one  array  location  for 
each  data  element  named  in  the  ENA  array.  If 
ICODA  (i)  is  set  to  3 by  FETCHN,  no  value  has 
been  loaded  for  element  ENA(i).  If  ICODA{i)  is 
set  to  6 by  FETCHN,  the  element  ENA(i)  is  not 
a valid  element  for  the  block  EN.  In  either  case, 
the  data  values  for  all  other  elements  named 
in  ENA  (and  which  have  a zero  in  the  appropriate 
locations  of  ICODA)  will  be  retrieved  and  placed 
into  the  DATA  array.  Other  error  conditions 
detected  by  FETCHN  will  cause  ICODA(l)  to  be 
set  to  the  appropriate  standard  error  code. 

BN  Data  block  name 

SBN  Subblock  name  or  number 

ENA  An  array  containing  the  names  of  one  or  more  non- 

repeating group  elements  having  values  to  be  re- 
trieved by  FETCHN.  The  array  must  contain  only 
one  name  per  location  (H  format,  le f t- j ust  i f ied ) ; 
the  last  location  of  ENA  must  be  set  to  zero. 

DATA  An  array  composed  of  consecutive  entries,  one 
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for  each  element  named  in  ENA  having  its  corre- 
sponding location  in  ICODA  a zero.  The  entry 
for  a single-valued  element  will  contain  simply 
the  element  value.  The  entry  for  an  array  element 
will  include  a dimension  word  followed  by  the 
array  values. 

LENGTH  As  an  input  parameter,  the  total  number  of  words  in 
DATA  that  can  be  used  for  retrieved  information; 
the  user  should  dimension  DATA  to  have  at  least 
LENGTH  words.  As  an  output  parameter,  the  number 
of  words  in  DATA  actually  containing  retrieved 
informat  ion . 


3.  FETCHR 

FETCHR  ( fCODA,  SBN,  RGN , RGO,  ENA,  DATA,  LENGW) 

FETCHR  retrieves  data  values  for  a set  of  repeating  group 
elements;  the  set  may  consist  of  single-valued  elements  and 
array  elements.  Values  may  be  retrieved  for  either  a specific 
occurrence  or  all  occurrences  of  a repeating  group. 

Parameters : 


ICODA 


t 

i 

I 


I 


An  array  of  error  codes,  one  location  for  each 
repeating  group  element  named  in  the  ENA  array. 

If  ICODA(i)  is  set  to  3 by  FETCHR,  the  element 
ENA{i)  has  no  value  loaded  for  the  occur rence ( s ) 
requested.  If  ICODA{i)  is  set  to  6 by  FETCHR, 
the  element  ENA(i)  is  not  a valid  element  for  block 
BN.  Other  error  conditions  will  cause  ICODA(l) 


! 
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BN 

SBN 

RGN 

RGO 


ENA 


DATA 


to  be  set  to  the  appropriate  standard  error  code. 

Data  block  name 
Subblock  name  or  number 

Repeating  group  name;  each  element  named  in  the 
ENA  array  must  be  a member  of  RGN 
Repeating  group  occurrence  number: 

= 0 Retrieve  all  occurrences 
= i,  where  i>0  Retrieve  ith  occurrence 
Whenever  all  occurrences  are  to  be  retrieved, 

RGO  will  be  an  output  parameter  indicating  the 
number  of  occurrences  actually  processed. 

An  array  containing  the  names  of  one  or  more 
repeating  group  elements  having  values  to  be 
retrieved.  The  array  must  contain  only  one  name 
per  location  (H  format,  left-justified);  the 
last  location  of  ENA  must  be  zero. 

An  array  composed  of  consecutive  entries,  one  for 
each  element  named  in  ENA  having  a value  other  than 
6 in  the  corresponding  ICODA  location;  the  entries 
are  made  in  the  same  order  as  were  the  ENA  names. 
Whenever  all  occurrences  of  a repeating  group  are 
to  be  retrieved,  all  entries  for  the  first  occurrence 
will  be  first,  all  entries  for  the  second  occurrence 
next,  etc.  The  entry  for  a single-valued  element 
will  be  either  a value,  or  an  octal  pattern  of 
76767676767676767676  signifying  no  value  has  been 
loaded  for  this  occurrence.  The  entry  for  an  array 


will  be  either  a dimension  word  followed  by  the 
array  values,  or  a zero  indicating  no  values 
have  been  loaded, 

LENGTH  An  an  input  parameter,  the  total  number  of  words 

in  DATA  that  can  be  used  for  retrieved  information; 
the  user  should  dimension  DATA  for  at  least  LENGTH 
words.  As  an  output  parameter,  LENGTH  is  the 
number  of  words  in  DATA  that  contain  retrieved 
information . 


4.  QUERY 

QUERY  ( ICODE,  LENGW,  FARM,  HITTYP) 

Recall  that  an  inverted  list  is  a directory  which  contains 
(a)  the  data  values  for  a particular  data  element  given  inversion 
status  when  it  was  defined,  and  (b)  the  names  of  all  blocks 
having  values  tor  the  inverted  elements.  QUERY  enables  the 
user's  program  to  search  inverted  lists  for  the  names  of  those 
data  blocks  that  satisfy  certain  user-specified  criteria.  The 
following  criteria  may  be  provided: 

(i)  A relational  expression,  that  is,  an  expression  either  of 
the  form 

element  name  operator  value 


where:  element  name 

operator 
value 


Name  of  inverted  element 
.EQ.,.GE.,.GT.,.LE.,.LT.,  or  .NE. 
Data  value  to  which  the  element's 
value  is  compared 


'< 

1 


1 

1 


\ 


I 
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or  of  the  form 


element  name  .BET.  value  1,  value  2 
where:  element  name  Same  as  above 

.BET.  Operator  indicating  that  only  values 

within  the  range  defined  by  value  1 
and  value  2 inclusive  will  be 
cons idered 

value  1,  value  2 Data  values  with  which  the  element's 

value  is  compared 

(ii)  A block-type  expression,  that  is,  an  expression  of  the 
f or  m : 

BT. EQ. type 

where:  type  Block  type  name 

(iii)  A combination  of  up  to  five  relational  and  block-type 
expressions  joined  by  the  Boolean  operators  .AND.  and  .OR., 
for  example, 

DEPTH. EQ. 10 .OR.HEIGHT.lt. 5. AND. WIDTH. BET. 20 , 30 
If  blocks  X,  Y,  and  Z have  element  DEPTH  equal  to  10,  and  if 

blocks  A,  B,  C,  and  D have  element  HEIGHT  less  than  5,  and  if 

blocks  C,  D,  G,  and  H have  element  WIDTH  between  20  and  30 

inclusive,  then  the  block  names  C,  D,  X,  Y and  Z will  be 

returned  to  the  user's  program.  Parentheses  may  be  used 
to  alter  the  normal  .AND.  over  .OR.  precedence. 

Parameters : 

ICODE  Standard  error  code 

LUN  Logical  unit  number  (in  the  range  1-99  inclusive) 

of  a "hit"  file  on  which  the  names  of  those  blocks 
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LENGTH 


FARM 


that  satisfy  the  user's  retrieval  criteria  will 
be  written.  The  file  is  organized  as  a set  of 
128-word  binary  records. 

As  an  input  parameter,  the  length  of  the  FARM 
array  (in  the  range  3-30  inclusive).  As  an 
output  parameter,  the  number  of  block  names 
written  on  the  "hit"  file. 

An  array  containing  the  user's  retrieval  criteria, 
one  array  location  for  each  item  expressed  in  the 
criteria.  Retrieval  items  include  parentheses, 
element  names,  relational  and  Boolean  operators, 
and  data  values.  Items  may  be  specified  in 
various  ways: 

(a)  By  parenthesis,  1H(  or  IH) 

(b)  By  element  name.  The  element  name  must  be 
H format,  lef t- j ust if ied . Moreover,  the 

two  rightmost  bits  of  the  location  containing 
the  element  name  must  indicate  the  data  type 
according  to  the  convention: 

0 real 

1 integer 

2 alphanumeric 

3 pointer 

(c)  By  relational  operator,  indicated  by  the 
integer  code: 

1 .BET. 

2 .EQ. 
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3  .GE. 


HITTYP 


4 .GT. 

5 .LE. 

6 .LT. 

7 .NE. 

(d)  By  Boolean  operator,  indicated  by  the  integer 
code : 

9 .AND. 

10  .OR. 

(e)  By  values.  Values  of  the  type  integer  or 
real  must  be  provided  in  FORTRAN  fixed  and 
floating  formats,  respectively.  Values  of 
the  type  alphanumeric  or  pointer  must  be 
provided  in  H forme' t,  lef  t- j ustif  ied  . 

Information  type  code: 

= 0 Write  only  data  block  names  (one  name  per 
word,  H format,  le f t- j us t i f ied  ) to  the  "hit"  file 
/ 0 VJrite  block  names  and  repeating  group 
occurrence  identifiers  to  the  "hit"  file.  (A 
repeating  group  occurrence  identifier  relates  an 
inverted  list  value  with  the  particular  repeating 
group  occurrence  which  contains  that  value.  The 
identifier  is  useful  only  in  a call  to  subroutine 
FETCHC  and  must  not  be  confused  with  the  repeating 
group  occurrence  number  so  frequently  used  by  the 
CDMS  host  language  subroutines.)  The  "hit"  file 
is  structured  in  the  following  manner: 
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.BNi 


BN  ( 

entry  | 


BN  i+1 


length! 

idl 

id2 


idn 

lengthi+1 


Repeating  group 
occurrence  identifiers 
for  block  BNi 


The  parameter  lengthiis  a 12-bit  quantity  equal 
to  the  number  of  id's  plus  one;  an  id  is  simply 
an  integer  value.  More  than  one  BN  entry  may  be 
present  in  the  128-word  "hit"  file  output  record: 
The  last  complete  entry  will  be  followed  by  a zero 
word;  the  next  entry  (if  one  exists)  will  begin 
in  the  first  word  of  the  next  output  record. 

Example : 

A user  desiring  to  know  which  of  the  United  States 
Presidents  born  between  1800  and  1899  were  members  of  the 
Republican  Party  might  formulate  the  retrieval  criteria 
YEARB.BET.  1800,  1899  .AND.  PARTY  .EQ.  REPUBLICAN 
and  might  code 

DIMENSION  IPARM  (8) 
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C SET  UP  IPARM  ARRAY  ACCORDING  TO  THE  RETRIEVAL  CRITERIA 


IPARM  (1)  = 5HYEARB 

IPARM  (1)  = OR  ( AND( IPARM( 1 ) , MASK ( 58 ) ) , 1 B ) 

C THE  ABOVE  STATEMENT  PACKS  THE  DATA  TYPE  (INTEGER)  FOR 
C THE  ELEMENT  YEARS 


IPARM 

(2)  = 

1 

IPARM 

(3)  = 

1800 

IPARM 

(4)  = 

1899 

IPARM 

(5)  = 

9 

IPARM 

(6)  = 

5HPARTY 

IPARM 

(6)  = 

OR  (AND( IPARM( 6) , MASK  (58)) 

IPARM 

(7)  = 

2 

IPARM 

(8)  = 

lOHREPUBLICAN 

LENGTH 

= 8 

CALL  QUERY  (ICODE,  35,  LENGTH,  IPARM,  0) 

IF  (ICODE. NE.O)  STOP  10 

C THE  FILE  TAPE35  WILL  NOW  CONTAIN  THE  NAMES  OF 
C THE  PRESIDENTS  THAT  SATISFY  THE  RETRIEVAL  CRITERIA 


I 

1 


i 


5.  FETCHC  1 

FETCHC(  ICODE , SBN , RGN , RGID,  EN , DATA,  LENGTH) 

FETCHC  allows  a user  to  retrieve  one  or  more  data  values 
from  a specific  repeating  group  occurrence  that  satisfies 
certain  user-specified  retrieval  criteria.  FETCHC  operates 
in  association  with  subroutine  QUERY  (discussed  previously). 
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Values  may  be  retrieved  for  either  a single  repeating  group 
element,  or  the  entire  repeating  group  occurrence. 

Parameters ; 

ICODE  Standard  error  code 

BN  Data  block  name 

SBN  Subblock  name  or  number 

RGN  Repeating  group  name;  used  only  when  an  entire 

occurrence  is  to  be  retrieved 

RGID  As  an  input  parameter,  a repeating  group  occurrence 

identifier  obtained  by  way  of  subroutine  QUERY; 
the  identifier  marks  the  occurrence  from  which 
values  will  be  retrieved.  As  an  output  parameter, 
the  number  of  the  repeating  group  occurrence 
containing  the  identifier  which  was  provided  as 
input . 

EN  A value  of  zero  if  one  occurrence  of  a repeating 

group  is  to  be  retrieved;  otherwise,  the  name 
of  the  data  element  to  be  retrieved. 

DATA  A user-supplied  work  space  used  to  store  the 

value(s)  retrieved  by  FETCHC.  If  a single-valued 
element  is  to  be  retrieved,  DATA  will  contain 
only  the  value  for  that  element.  If  an  array 
is  to  be  retrieved,  DATA  will  contain  a dimension 
word  followed  by  the  array  values.  If  an  entire 
occurrence  is  to  be  retrieved,  DATA  will  be 
composed  of  consecutive  entries,  one  for  each 
member  of  the  repeating  group.  The  entries  will 
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be  ordered  in  the  same  way  as  the  repeating  group 
elements  are  defined  in  the  block  type.  The  entry 
for  a single-valued  element  will  be  either  a value, 
or  an  octal  pattern  of  76767676767676767676 
signifying  no  value  has  been  loaded  for  the 
occurrence.  The  entry  for  an  array  will  be  either 
a dimension  word  followed  by  the  array  values,  or 
a zero  indicating  no  values  have  been  loaded. 

LENGTH  As  an  input  parameter,  the  total  number  of  words 

in  DATA  that  can  be  used  for  retrieved  information; 
the  user  must  dimension  DATA  to  have  at  least 
LENGTH  words.  As  an  output  parameter,  the  number 
of  words  in  DATA  which  actually  contain  retrieved 
information. 


6 . NOCC 

NOCC(  fcODE,  SBN,  RGN,  RGO ) 

NOCC  determines  the  number  of  repeating  group  occurrences 
that  exist  within  a given  data  block. 

Parameters : 

ICODE  Standard  error  code 

BN  Data  block  name 

SBN  Subblock  name  or  number 

RGN  Name  of  the  repeating  group  for  which  a count  of 

the  occurrences  is  to  be  determined 
RGO  Number  of  occurrences  for  RGN 
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7. 


INPFN 


L 


INPFN( ICODE,  DATA,  PFN,  ID,  FILTYP) 

INPFN  retrieves  the  name  of  the  permanent  file  referenced 
by  a cross-file  pointer.  An  index,  inserted  into  the  pointer 
by  subroutine  PFNIN,  indicates  where  in  the  cross-file  reference 
table  the  file  name  is  stored. 

Parameter : 

ICODE  Standard  error  code 

DATA  A variable  containing  a pointer  of  as  many  as 

eight  characters  ( lef t- j ust i f ied , H format),  and 
a cross-file  reference  table  index  (in  the  12 
right-most  bit  positions).  If  the  index  is  zero, 
signifying  a within-file  pointer,  PFN  and  ID  will 
each  contain  10  blanks  on  return  from  INPFN. 

PFN  Name  of  the  file  containing  the  block  referenced 

by  the  value  in  DATA.  If  a SCOPE  file,  PFN  will 
contain  the  permanent  file  name  of  as  many  as  40 
characters.  If  a CPFMS  file,  PFN  will  contain 
the  level-!  name  of  as  many  as  eight  characters, 
lef  t- j ust  i f ied  , FI  format. 

ID  For  a SCOPE  file,  the  four-character  ID;  for  ?. 

CPFMS  file,  the  level-4  name  of  as  many  as  e.ght 
characters,  le f t- j us t i f ied , H format. 

FILTYP  File  type  code: 

= 0 SCOPE  file 
= 1 CPFMS  file 
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COMRADE  PERMANENT  FILE  MANAGEMENT  SYSTEM 

The  COMRADE  Permanent  File  Management  System  (CPFMS)  affords 
the  COMRADE  user/pr ogrammer  a special  file  management  capability 
otherwise  not  available  under  the  SCOPE  permanent  file  system. 
Using  CPFMS,  the  user/programmer  is  able  to  limit  access  to  only 
those  persons  associated  with  a particular  design  project.  This 
control  is  achieved  by  creating  CPFMS  files  which  may  only  be 
accessed  from  within  a COMRADE  application  system. 

FILE-NAMING  CONVENTION 

Each  CPFMS  file  is  assigned  a unique  four-level  designation. 
The  LI  (first-level)  name  CPFM  is  given  to  all  CPFMS  files.  The 
L2  (second-level)  name  is  that  of  the  application  system  with 
which  the  file  is  associated  (for  example,  ISDS).  The  L3  (third- 
level)  name  is  that  of  a project  within  the  application  system 
with  which  the  file  is  associated  (for  example,  DDG3).  The  L4 
(fourth-level)  name  may  be  freely  chosen;  it  is  used  to  suggest 
the  contents  of  the  file  (WEIGHTS,  for  example).  The  L2,  L3, 
and  L4  names  are  concatenated,  with  dashes,  to  form  a unique 
permanent  file  name  which  can  be  processed  by  the  SCOPE  per- 
manent file  system.  Each  level  name  many  be  composed  of  as 
many  as  eight  characters.  The  designation  ISDS-DDG3-USERS 
(with  ID=CPFM)  typifies  the  structure  of  a CPFMS  file  name. 


FILE  ACCESS  CONTROL 


CPFMS  files  may  be  used  only  within  the  application  system 
for  which  they  were  created;  thus  only  the  L3  and  L4  names 
actually  need  be  submitted  by  the  would-be  user.  Two  schemes 
for  controlling  access  to  CPFMS  files  from  within  application 
systems  are  provided — the  pseudo-password,  and  the  File-Access- 
Key/File-Access-Lock  (FAK/FAL).  Both  are  assigned  at  the  time 
the  file  is  cataloged  within  the  CPFMS  system.  If  the  pseudo- 
password is  used,  access  to  that  file  will  require  that  the 
user  submit  a pseudo-password  for  a check.  If  the  password 
submitted  by  the  user  is  identical  to  the  one  assigned  at 
the  time  the  file  was  cataloged,  access  is  granted. 

If  the  FAK/FAL  is  used,  the  operation  is  more  complex.  The 
FAL  assigned  to  a file  consists  of  a 20-bit  field,  each  bit 
associated  with  a different  aspect  of  a project  effort  (for 
example,  the  hull  design  portion).  The  FAK  assigned  to  each 
COMRADE  user  consists  of  60  bits,  organized  into  three  20-bit 
fields  called  sub-FAK's.  Each  of  the  three  sub-FAK's  pertains 
to  a different  level  of  file  access:  (1)  Attach  with  read 
permission  only;  (2)  Attach  with  read-write  permission;  or 
(3)  Attach  with  purge  permission.  Each  bit  of  the  20-bit 
sub-FAK  may  itself  be  associated  with  a particular  subset  of 
the  project  effort.  Those  sub-FAK  bit  positions  that  corre- 
spond to  the  subsets  that  the  user  is  allowed  to  use  will  con- 
tain I's.  Each  of  the  20-bit  sub-FAK's  will  be  compared  with 
the  FAL  of  the  file  in  question  to  determine  which,  if  any,  of 
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these  levels  of  file-access  will  be  permitted  that  particular 
user.  The  FAK/FAL  check  will  be  considered  a success  {that  is, 
access  will  be  granted)  if  the  bits  in  the  user's  20-bit 
sub-FAK  that  correspond  to  the  1-bits  contained  in  the  FAL 
are  1 ' s . 
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APPENDIX  B 


DTNSRDC  CHARACTER  SET 


DISPLAY 

CHARACTER 

PUNCH 

PUNCH 

7-TRACK 

NOTE 

CODE 

026 

029 

TAPE 

NAME 

IF 

DIFF 

01 

AAA 

12-1 

61 

02 

BBB 

12-2 

62 

03 

CCC 

12-3 

63 

04 

DDD 

12-4 

64 

05 

EEE 

12-5 

65 

06 

FEE 

12-6 

66 

07 

GGG 

12-7 

67 

10 

HHH 

12-8 

70 

11 

III 

12-9 

71 

12 

JJJ 

11-1 

41 

13 

KKK 

11-2 

42 

14 

LLL 

11-3 

43 

15 

MMM 

11-4 

44 

16 

NNN 

11-5 

45 

17 

000 

11-6 

46 

20 

PPP 

11-7 

47 

21 

QQQ 

11-8 

50 

22 

RRR 

11-9 

51 

23 

SSS 

0-2 

22 

24 

TTT 

0-3 

23 

25 

UUU 

0-4 

24 

26 

VVV 

0-5 

25 

27 

WWW 

0-6 

26 

30 

XXX 

0-7 

27 

31 

YYY 

0-8 

30 

32 

Z^Z 

0-9 

31 

33 

000 

0 

12 

34 

111 

1 

01 

35 

222 

2 

02 

36 

333 

3 

03 

37 

444 

4 

04 

40 

555 

5 

05 

41 

666 

6 

06 

42 

111 

7 

07 

43 

888 

8 

10 

44 

999 

9 

11 

45 

+ + + 

12 

12-8-6 

60 

PLUS 

46 

— 

11 

40 

MINUS 

47 

ir  n it 

11-8-4 

54 

ASTERISK 

50 

/// 

0-1 

21 

SLASH 

51 

( { ( 

0-8-4 

12-8-5 

34 

LEFT  PAR 

52 

) ) ) 

12-8-4 

11-8-5 

74 

RT  FAR 

53 

$$$ 

11-8-3 

53 

DOLLAR 

71 


PAGE  MOT  FIXMED 

fiUAIK 


DISPLAY 

CHARACTER 

PUNCH 

PUNCH 

7-TRACK 

NOTE 

CODE 

026 

029 

TAPE 

NAME 

IF 

DIFF 

54 

= =:s: 

8-3 

8-6 

13 

EQUAL 

55 

20 

BLANK 

56 

r f f 

0-8-3 

33 

COMMA 

57 

• • • 

12-8-3 

73 

PERIOD 

60 

### 

0-8-6 

8-3 

36 

POUND 

61 

[ [ [ 

8-7 

12-8-2 

17 

L BRACKET 

62 

] ] ] 

0-8-2 

11-8-2 

32 

R BRACKET 

63 

t • ! 

8-2 

COLON 

64 

II  II  II 

8-4 

8-7 

14 

QUOTE 

65 

0-8-5 

35 

UNDERLINE 

66 

11-8-2 

12-8-7 

52 

EXCLAMATION 

66 

11-0 

52 

EXCLAMATION 

67 

&&& 

0-8-7 

12 

37 

AMPERSAND 

70 

1 1 1 

11-8-5 

8-5 

55 

APOSTROPHE 

71 

??? 

11-8-6 

0-8-7 

56 

QUESTION 

72 

12-8-2 

12-8-4 

72 

LESS  THAN 

72 

12-8 

72 

LESS  THAN 

73 

11-8-7 

0-8-6 

57 

GREATER 

74 

@@@ 

8-5 

8-4 

15 

AT 

75 

12-8-5 

0-8-2 

75 

REVERSE  SLANT 

76 

12-8-6 

11-8-7 

76 

CIRCUMFLEX 

77 

1 ? ? 

12-8-7 

11-8-6 

77 

SEMICOLON 

55 

8-6 

0-8-4 

BLANK 

72 


APPENDIX  C 


SUMMARY  OF  CDMS  STORAGE  CAPACITIES 


MAXIMUM  DATA  BLOCK  STORAGE  CAPACITIES: 

Number  of  data  blocks  on  each  file 2**53-l 

Number  of  words  in  each  data  block 262,143 

Number  of  blocks  that  may  be  saved  at  any  one  time 

for  reallocation 81,090 

Number  of  full  or  partial  data  blocks  that  may  be 


contained  in  buffer  at  any  one  time 20 

MAXIMUM  INVERTED  LIST  STORAGE  CAPACITIES: 

Number  of  inverted  element  lists  per  file 100 

Number  of  entries  per  inverted  list  element 173,740 


Number  of  qualifying  inverted  list  entries  per  query.  64,897 


MAXIMUM  BLOCK  TYPE  STORAGE  CAPACITIES: 

Number  of  block  types  on  each  file 100 

Number  of  data  elements  per  block  type 250 

Number  of  subblocks  per  block  type 8 

Number  of  repeating  groups  per  subblock 14 

Number  of  elements  per  repeating  group 50 
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APPENDIX  D 


HOST  LANGUAGE  INTERFACE  OPERATING  PROCEDURES 


A.  SUBROUTINE  ACCESS 

The  subroutines  constituting  the  CDMS  host  language  inter- 
face reside  on  a program  library  created  by  way  of  the  SCOPE 

3 

EDITLIB  capability.  This  library,  a SCOPE  permanent  file  on 
DTNSRDC's  Control  Data  6700  computer,  is  named  SUBLIB,  ID=COMR. 
All  users  are  automatically  assigned  "read  only"  permission 
when  they  access  SUBLIB  for  use  in  creating  their  application 
programs.  SUBLIB  contains  five  groups  of  subroutines: 

. CDMS  host  language  interface  subroutines,  both  the  user- 
callable  and  the  more  primitive  subroutines. 

. COMRADE  utility  subroutines  (see  Appendix  E) 

. Absolute  Subroutine  Utility  (ASU)  subroutines  which  are 
required  for  the  access  of  the  COMRADE  Absolute  Sub- 
routine Library  (see  Appendix  F) 

. ALPHAPACK  subroutines  which  are  used  for  alphanumeric 
data  conversion  (see  Appendix  G) 

. Permanent  file  management  subroutines  (Appendix  H) 

The  control  statements  needed  to  access  the  host  language 
interface  subroutines  for  the  purpose  of  creating  an  application 
program  are 
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source  code  for  HULLDEF  and  then  load  the  object  code  including  \ 

the  host  language  subroutines,  and  would  then  execute  the  I 

program:  | 

FIN,  I = HULLDEF.  j 

1 

ATTACH,  SUBLIB,  ID  = COMR.  j 

LIBRARY,  SUBLIB.  j 

LDSET,  USER  = DBMF/CDSF/CDSFI . 1 

LGO.  j 

i 

There  are  two  variations  to  this  procedure  that  are  worth  j 

investigation  by  a CDMS  user:  i 

(1)  Suppression  of  the  Automatic  Reprieve  Feature.  The 
standard  use  of  SUBLIB  (just  described)  provides  for  an  auto- 
matic "reprieve"  from  abnormal  terminations  such  as  an  address 
out-of-range,  or  the  use  of  an  infinite  or  indefinite  operand 
in  an  arithmetic  expression.  The  user  who  does  not  wish  his 
program  to  be  reprieved  can  circumvent  the  automatic  "reprieve" 
by  inserting  the  statement 

LDSET,  SUBST  = OPEN-ZNOPEN. 
preceding  the  LGO  statement. 

(2)  Inverted  List  Bypass.  The  CDMS  host  language  subroutine 
IFLN  supports  the  option  of  by-passing  the  processing  of  any  in- 
verted list  transactions.  Use  of  this  option  could  result  in  a 
core  saving  of  approximately  7000  (octal)  locations,  since  the 
subroutines  and  labelled  common  blocks  required  to  process  the 
transactions  would  not  be  needed.  The  user  who  does  not  wish 
his  program  to  contain  the  inverted  list  processing  software 
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should  insert  the  statements 


LDSET,SUBST=ADDIE-ZNADDIE/CHNGIE-ZNCHGI E/DELI E-ZNDELIE, 
LDSET,SUBST=BRKUP-ZNBRKP/REFILE-ZNRFILE 
before  the  LGO  statement,  and  should  remove  the  designation 
/CDFSI  from  the  LDSET,USEP  statement.  The  inverted  list  pro- 
cessing software  is  used  by  many  of  the  host  language  update 
subroutines;  only  one  retrieval  subroutine,  QUERY,  accesses 
inverted  lists. 

B.  CORE  REQUIREMENTS 

Of  the  approximately  250  subroutines  on  SUBLIB,  60-70  are 
user-callable.  Since  these  subroutines  are  not  mutually  ex- 
clusive (that  is,  subroutines  A,  B,  and  C might  each  call  sub- 
routine X,  but  subroutine  A might  also  call  subroutine  Y;  sub- 
routine B might  also  call  subroutine  Z ; while  subroutine  C 
might  call  Y and  Z),  computation  of  the  core  requirements 
of  a particular  application  program  is  difficult.  One  way 
of  estimating  these  core  requirements  is  by  constructing 
a dummy  program  that  calls  the  needed  SUBLIB  subroutines, 
and  then  allowing  the  system  loader  to  compute  the  storage 
needs.  Thus,  a user  desiring  to  estimate  the  core  required 
for  subroutines  SBUFF,  ILFN,  FETCH,  CHANGE,  ADDO , and  FLFN 
might  code 

PROGRAM  TEST 
CALL  SBUFF 
CALL  ILFN 
CALL  FETCH 
CALL  CHANGE 
CALL  ADDO 
CALL  FLFN 
END 


The  control  statements  needed  to  effect  loading  of  such  a 
program  are 
FTN. 

MAP,  ON. 

ATTACH,  SUBLIB,  ID  = COMR. 

LIBRARY,  SUBLIB. 

LOAD,  LGO. 

NOGO. 

Following  inspection  of  the  system  loader's  computations,  the 
user  could  determine  the  need  for  a sophisticated  program 
structuring  facility  such  as  overlay  , segmentation  , or  the 
COMRADE  Absolute  Subroutine  Utility^  (see  Appendix  F). 
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APPENDIX  E 


COMRADE  UTILITY  SUBROUTINES 

The  library  SUBLIB  contains  a set  of  utility  subroutines 
which  have  been  found  to  be  quite  useful  to  DTNSRDC  Control 
Data  6700  programmers.  The  subroutines  allow  an  application 
program  to 

. pack  a value  into  a user-specified  field  within  a given 
word  (PACK), 

. unpack  a value  from  a user-specified  field  within  a 
given  word  (UNPACK), 

. change  blank  characters  to  binary  zeros  (FILL), 

. determine  whether  the  calling  program  is  executing  in 
the  conversational  or  batch  mode  (RWE), 

. compress  blank  characters  from  a card  image  (RPK),  and 
. terminate  the  user  program  (TERMJOB). 

Individual  descriptions  of  the  utility  subroutines  follow. 

1.  PACK  (TO,  I^  IR,  FROM,  ICODE) 

PACK  packs  a value  into  a user -spec i f ied  field  within  a 
given  computer  word. 

Parameters : 

TO  A word  into  which  a value  will  be  packed 

IL,  IR  The  leftmost  and  rightmost  bit  positions,  re- 
spectively, of  the  field  within  TO  into  which 
a value  will  be  packed.  According  to  convention, 
the  bits  of  a Control  Data  6700  word  are  numbered 
rxght  to  left,  0 through  59;  thus  59  ^ILl  IRl  0. 
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FROM 


Value  to  be  packed  in  TO 
ICODE  Error  code: 

=0  No  error  detected 
= 1 IL  1 59 
= 2 IR  £0 
= 3 IR  ^IL 

' = 4 Value  too  large  for  the  field  specified 

Example : 

Suppose  that  the  variables  I and  J have  the  following  bit 
patterns : 


I 


59  58  57 

111 


59  58 

J 0 0 

After  the  statement 


57 

0 


38  37  36  35 

1111 

38  37  36  35 

0 0 0 0 


3 2 10 
1111 

3 2 10 
10  0 1 


CALL  PACK  (I,  38,  35,  J,  ICODE) 
has  been  executed,  I will  have  the  contents 

59  58  57  38  37  36  35  3 2 1 0 

1 1 1...1  0 0 1...1111 

and  J will  be  unchanged. 

2.  UNPACK 

UNPACK  (FROM,  IL,  IR,  TO,  ICODE) 

UNPACK  unpacks  a value  from  a user-specified  field  within 
a given  computer  word. 

Parameters : 


FROM  A word  from  which  a value  will  be  unpacked. 
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IL,  IR  The  leftmost  and  rightmost  bit  positions,  re- 
spectively, of  the  field  within  FROM  from  which  a 
value  will  be  unpacked.  The  bit  positions  of  a 
Control  Data  6700  word  are  numbered  right  to  left, 
0 througu  59;  thus  59^IL>  IR^O. 

TO  A word  into  which  the  unpacked  value  will  be 

placed,  r ight-justif ied. 

ICODE  Error  code: 

=0  No  error  detected 
= 1 ILl  59 
= 2 IRl  0 
= 3 IRl  IL 

Example : 

Suppose  the  variable  I has  the  following  bit  pattern 
59  58  57  56  55  0 

1 0 0 1 1 ...  1 

After  the  statement 

CALL  UNPACK  (I,  59,  56,  J,  ICODE) 
has  been  executed,  J will  have  the  contents 
59  3210 

0 ...  0 1 0 0 1 
and  I will  be  unchanged. 

3.  FILL 

FILL  (NAME,  ICODE) 

FILL  changes  blank  characters  (display  code  55  octal)  in  a 
given  computer  word  to  binary  zeros  (display  code  00)  and  vice 
versa . 
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Parameters : 


NAME  Location  containing  the  characters  to  be  changed. 

ICODE  Change  code: 

= 1 Zeros  to  blanks 
= 2 Blanks  to  zeros 

4 . RWE 

RWE  (MODE) 

RWE  determines  whether  the  application  program  is  executing 
in  conversational  or  batch  mode. 

Parameters : 

MODE  Operation  code: 

= 0 Batch  mode 
= 1 Conversational  mode 

5.  RPK 

RPK  ( STRING,  LAST) 

RPK  compresses  blank  characters  from  an  80-character  card 
image . 

Parameters : 

STRING  As  an  input  parameter,  an  8-word  array  containing 
the  card  image  to  be  compressed.  As  an  output 
parameter,  a set  of  non-blank  characters,  left- 
justified,  H format. 

Number  of  non-blank  characters  in  STRING. 
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LAST 


6.  TERMJOB 


TERMJOB 

TERMJOB  terminates  the  application  program,  producing  no 
day-file  messages  and  eliminating  the  need  for  a FORTRAN  STOP 
statement . 
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APPENDIX  F 


USE  OF  THE  COMRADE  ABSOLUTE  SUBROUTINE  LIBRARY 

A.  SUBROUTINE  ACCESS 

The  COMRADE  Absolute  Subroutine  Utility  (ASU)  ^provides  a 
capability  for  loading  and  executing  the  CDMS  host  language 
subroutines  as  well  as  those  auxiliary  subroutines  identified 
in  Appendix  D.  Two  ASU  subroutines  - INITLDR  and  COMRLDR  - 
are  used  to  load  and  execute  CDMS  subroutines  from  an  Absolute 
Subroutine  Library  (ASL).  Use  of  an  ASL  offers  the  following 
benefits: 

! . The  amount  of  core  required  to  run  an  application  program 

I can  be  reduced,  since  the  CDMS  host  language  subroutines 

I (and  the  auxiliary  software)  can  execute  within  the  same 

[ core  area. 

t 

[ . Only  one  copy,  the  latest,  of  the  CDMS  subroutines  is 

needed,  since  the  subroutines  reside  on  an  ASL  that  is 
designed  to  be  shared  by  many  application  programs. 

Since  ASL  subroutines  are  separate  from  an  application 
program,  subroutine  errors  can  be  corrected  without 
requiring  that  users  recreate  their  programs. 

1 . Parameters  may  be  passed  to  and  among  ASL  subroutines 

; either  as  arguments  in  the  CALL  to  COMRLDR,  or  through 

i a shared  common  block. 

I 

I . No  instruction  modification  is  needed  since  ASL  sub- 

I routines  are  in  absolute  form. 

I 

I 


Two  permanent  files  are  required  when  the  COMRADE  ASL  sub- 
routines are  to  be  used.  The  files  are  named  ASL,  ID  = COMR 
and  SUBLIB,  ID  = COMR.  The  file  named  ASL  contains  COMRADE 
subroutines  in  absolute  form  and  must  be  attached  whenever  an 
application  program  is  to  be  executed.  The  file  named  SUBLIB 
(discussed  in  Appendix  D)  contains  the  subroutines  INITLDR  and 
COMRLDR  and  is  required  when  the  application  program  is  being 
created.  Descriptions  of  the  two  subroutines  follow. 

1.  INITLDR 

INITLDR  (LFN,  NAME,  TeRR) 

INITLDR  identifies  the  ASL  file  that  contains  the  COMRADE 
subroutines  in  absolute  form.  INITLDR  should  be  called  only 
once  in  an  application  program,  before  the  first  CALL  to 
COMRLDR. 

Parameters : 

LFN  Logical  file  name  ( lef t- j ust  if  ied  , H format)  of 

the  ASL  file. 

NAME  Reprieve  indicator: 

=0  No  reprieve  subroutine  is  to  be  executed 
= REFILE  ( lef t- justif  ied  , H format)  A reprieve 
subroutine  (developed  by  COMRADE  system  personnel) 
named  REFILE  will  be  executed  following  an  abnormal 
error  condition;  REFILE  closes  and  finalizes  the 
CDMS  data  base  file  active  at  the  time  of  the 
error.  If  a user-developed  subroutine  is  to  be 
executed,  the  name  of  that  subroutine,  instead 
of  REFILE,  must  appear  in  NAME. 
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lEER  Error  code 

=0  No  error  detected 
i 0 File  not  in  ASL  format 

2.  COMRLDR 

COMRLDR  (SUB,  PARMl , PARM2 , . . . PARMN ) 

COMRLDR  loads  and  executes  a specific  ASL  subroutine.  If 
the  subroutine  is  already  in  memory,  execution  will  proceed 
directly.  If  it  is  not  resident  on  the  current  ASL,  the 
message  INVALID  SUBROUTINE  NAME  will  be  written  to  the  dayfile 
and  the  program  will  be  aborted.  If  subroutine  INITLDR  has  not 
been  called,  the  message  INITLDR  NOT  CALLED  will  be  written 
to  the  dayfile  and  the  program  aborted. 

Parameters : 

SUB  The  name  ( le f t- j us t i f ied , H format)  of  the  ASL 

subroutine  that  is  to  be  executed. 

PARMl-  The  parameters  to  be  passed  to  the  subroutine 
PARMN  identified  by  SUB;  the  list  is  variable-length. 
Example: 

CALL  COMRLDR  (4HILFN,  lERR,  3HSDF,  0,  1) 

CALL  COMRLDR  (5HFETCH,  ICODE,  BN,  SBN,  RGN , RGO , EN , DATA, 
LENGTH) 

B.  CORE  REQUIREMENTS 

Before  ASL  subroutines  can  be  used,  a core  area  in  which  the 
subroutines  will  execute  must  have  been  defined.  This  area 
must  coincide  with  the  area  in  which  the  subroutines  have  been 
designed  to  execute,  otherwise  an  error  will  occur.  The  COMRADE 


I 


\ 


■i 
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ASL  subroutines  have  been  designed  to  execute  in  an  area  that 
begins  at  location  101  (octal)  and  will  require  a maximum  of 
20K  (octal)  words.  A smaller  area  may  be  provided,  depending 
on  the  specific  subroutine  to  be  called.  Once  the  size  of 
the  area  has  been  determined,  it  can  be  reserved  by  way  of 
a FORTRAN  labelled  common  statement  placed  immediately  after 
the  PROGRAM  statement.  The  statement  may  appear  as 
COMMON/AREA/DUM  (20000B) 

A ] ist  of  subroutines  resident  on  the  file  ASL,  ID  = COMR 
follows.  The  core  requirement  for  each  is  indicated. 


COMRADE  ASL  SUBROUTINES 


NAME 

LENGTH  (OCTAL) 

NAME 

ADDO 

17101 

FETCHC 

ADDU 

16770 

FETCHN 

ATTACH 

7315 

FETCHR 

BLKLEN 

7276 

FLFN 

BRKUP 

12010 

FTNBIN 

CAD 

17131 

GET 

CAI 

17076 

GETCOM 

CAO 

17070 

ILFN 

CAR 

17114 

INPFN 

CATLOG 

7315 

LOCATE 

CDA 

17204 

LSHIFT 

CHANGE 

17725 

MODBN 

CHANGO 

17375 

MOVE 

CIA 

17277 

NOCC 

CLUNLD 

11516 

PACK 

CLRWND 

11516 

PASOVR 

COA 

17277 

PERM 

COMATC 

15271 

PFNIN 

COMCAT 

1 5540 

PURGE 

COHPRG 

1 5320 

QUERY 

COMUNL 

1 3535 

REFILE 

CRA 

17202 

RENAME 

CULL 

13727 

REQUEST 

DEFFIL 

7134 

RPK 

DEFINE 

16550 

RWE 

DELETE 

17261 

SBUFF 

DELETE 

17433 

SETCH 

DISPOS 

15411 

SETCOM 

EMPTY 

6312 

UNPACK 

EXTEND 

7120 

ZADDOM 

FETCH 

13341 

ZGENCOM 
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LENGTH  (OCTAL) 
12633 
12515 
1 3503 
15155 
1 2355 
10221 
7107 
10713 
6254 
6322 
6213 
15722 
6276 
12266 
6250 
7756 
7120 
6644 
7315 
17524 
12304 
7315 
6422 
6330 
6203 
6747 
6241 
7107 
6213 
6711 
6711 


C.  SAMPLE  PROGRAM  USING  THE  COMRADE  ASL 


In  the  example  that  follows,  CDMS  subroutines  SBUFF,  ILFN, 
DEFINE,  and  FLFN  are  called  to  define  a data  block  named  JONES. 
The  COMRADE  ASL  file  has  been  previously  attached  as  LIB. 
PROGRAM  SAMPLE 
COMMON/AREA/DUM  (20000B) 

DIMENSION  IBUFF  (1025) 

CALL  INITLDR  (3HLIB,  6HREFILE,  lERR) 

IF  (lERR.NE.O)  STOP  10 

CALL  COMRLDR  (5HSBUFF,  lERR,  IBUFF,  1025) 

IF  (lERR.NE.O)  STOP  20 

CALL  COMRLDR  (4HILFN,  lERR,  6HCDMSDB,  0,  0) 

IF  (lERR.NE.O)  STOP  30 

CALL  COMRLDR  (6HDEFINB,  lERR,  5HJONES,  8HPERSONAL) 

IF  (lERR.NE.O)  STOP  40 

CALL  COMRLDR  (4HFLFN,  lERR,  6HCDMSDB) 

IF  (lERR.NE.O)  STOP  50 
END 
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APPENDIX  G 


ALPHANUMERIC  DATA  CONVERSION  SUBROUTINES 

The  library  SUBLIB  contains  a set  of  subroutines  which  have 
been  found  to  be  useful  to  programmers  who  must  manipulate  and 
convert  alphanumeric  data.  The  set,  known  as  ALPHAPACK, 
provides  for  comparing  and  moving  character  strings,  and  for 
converting  strings  to  internal  representations  for  octal, 
integer,  real,  and  double-pre vision  numbers,  and  vice  versa. 

The  ALPHAPACK  subroutines  are  summarized  as  follows; 

SETCH  Sets  a given  character  into  an  array 

MOVE  Moves  a character  string  from  one  array 

to  another 

LOCATE  Searches  for  the  location  of  one  string 
within  another 


LSHIFT 

Performs 

a 

logical  shift 

CAI 

Conve  r ts 

a 

numeric  string 

to  an 

1 integer 

CIA 

Conve  r ts 

an 

integer  to  a 

numeric  string 

CAR 

Converts 

a 

numeric  string 

to  a 

real  number 

CRA 

Converts 

a 

real  number  to 

a numeric  string 

CAO 

Converts 

an 

octal  string 

to  an 

octal  number 

COA 

Converts 

an 

octal  number 

to  an 

octal  string 

CAD 

Converts 

a 

numeric  string 

to  a 

double- 

precision 

number 

CDA 

Converts 

a 

double-precision  number  to  a 

numeric  string 
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ALPHAPACK  returns  the  following  error  codes: 

0 No  error  detected 

1 An  illegal  character  or  format  encountered 

2 Character  string  contains  more  characters  than  allowed 

3 The  character-positioning  parameter  is  less  than  1 

4 The  number  of  characters  in  the  string  is  less  than  1 
Individual  descriptions  of  the  ALPHAPACK  subroutines  follow. 

1 . SETCH 

SETCH  (ARRAY,  NBR,  CHAR,  fERR) 

SETCH  fills  all  or  part  of  an  array  with  a specified 
character . 

Parameters : 

ARRAY  Name  of  the  array  to  be  filled 

IL  First  character  position  of  ARRAY  to  be  filled 

NRR  Number  of  character  positions  to  be  filled 

CHAR  Character  (IR  format)  to  be  inserted  into  NBR 
positions  of  ARRAY. 
lERR  Standard  error  code 

Example : 

CALL  SETCH  (ARRAY,  1,  5,  IR*,  lERR) 

2 . MOVE 

MOVE  ( ARRAY  1,  lU.,  ARRAY 2,  I^,  NBR,  fEi^) 

MOVE  moves  a character  string  from  one  array  to  another. 
Parameters : 

ARRAYl  Name  of  the  array  that  is  to  receive  the  character 
string 

ILl  First  character  position  of  ARRAYl  to  be  filled 
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ARRAY2  Name  of  the  array  containing  the  character  string 


to  be  moved. 

IL2  First  character  position  of  ARRAY2  to  be  moved. 

NBR  Number  of  characters  to  be  moved 

lERR  Standard  error  code 

Example : 

CALL  MOVE  (ARRAY,  1,  ARRAY(4),  6,  15,  lERR) 

Upon  execution  of  this  statement,  15  characters  beginning, 
with  the  sixth  character  position  of  ARRAY(4),  will  be  moved  to 
the  first  character  position  of  ARRAY ( 1 ) . FORTRAN  word  bound- 
aries are  not  regarded  as  meaningful  when  MOVE  is  executing. 

An  alternate  form  of  the  above  statement  is 

CALL  MOVE  (ARRAY,  1,  ARRAY,  36,  15,  lERR) 

3.  LOCATE 

LOCATE  (ARRAYl  , ILl  , NBRl  , ARRAY2 , IL2 , NBR2,  L^,  I ERR) 
LOCATE  searches  for  the  location  of  one  character  string 
(the  one  to  be  matched)  within  another  string  (the  one  to  be 
searched).  If  a match  is  realized,  the  position  of  the  first 
character  of  the  matching  string  is  returned  to  the  calling 
program. 

Parameters : 

ARRAYl  Name  of  the  array  containing  the  string  to  be 
matched 

ILl  First  character  position  of  ARRAYl 

NBRl  Number  of  characters  within  ARRAYl 

ARRAY2  Name  of  the  array  containing  the  string  to  be 
searched 
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IL2 


I 

I 

I 

[ 

i 


First  character  position  of  ARRAY2 

NBR2  Number  of  characters  within  ARRAY2 

LOC  Match  indicator: 

= 0 No  match  found 

= i where  i >0  First  character  position  of  the 
matching  string  within  ARRAY2 
lERR  Standard  error  code 

Example : 

If  the  contents  of  the  first  three  words  (30  characters) 

of  the  array  ARRAY  were 

FOUR  SCORE  AND  SEVEN  YEARS  AGO 
1 10  20  30 

then  following  execution  of  the  statement 

CALL  LOCATE  (5HSEVEN,  1,  5,  ARRAY,  1,  30,  LOC,  lERR) 

the  parameter  LOC  would  be  set  to  16. 

4.  LSHIFT 

LSHIFT  ( IWORD,  NBITS) 

LSHIFT  performs  left  and  right  logical  shifts,  i.e.,  shifts 
that  are  neither  end-around  nor  signed-extended.  Note  that 
LSHIFT  is  the  only  function  subprogram  described  in  this  manual. 
Parameters : 

IWORD  Word  to  be  shifted 

NBITS  Indicates  the  number  of  bit  positions  involved  and 
the  direction  in  which  the  contents  of  IWORD  are 
to  be  shifted.  If  NBITS  contains  a positive  in- 
teger, a left  logical  shift  will  be  performed;  if 
a negative  integer,  a right  logical  shift  will  be 
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will  be  performed. 

Example : 

If  the  contents  of  IWORD  are  00000 ... 01 1 1000000 , the 
statement 

N = LSHIFT  (IWORD,  2) 

when  executed  would  result  in  N having  the  value  of  00000... 
011100000000.  The  statement 

N = LSHIFT  (IWORD,  -5) 

when  executed  would  result  in  having  the  value  00000 . . . 01 1 10 . 

5.  CAI 

CAI  ( INTEGER,  ARRAY,  IL,  lERR) 

CAI  converts  a numeric  string  (display  code)  to  an  integer. 
The  string  may  contain  no  more  than  14  characters. 

Parameters : 

INTEGER  Location  to  receive  the  integer 

ARRAY  Name  of  the  character  string  to  be  converted. 

IL  First  character  position  in  ARRAY 

IR  Last  character  position  in  ARRAY 

lERR  Standard  error  code 

Example : 

If  the  contents  of  ARRAY  were  ABCD12GHIJ,  the  statement 
CALL  CAI  (INT,  ARRAY,  5,  6,  lERR) 
when  executed  would  result  in  INT  having  the  value  12  in  fixed 
format . 
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6.  CIA 


CIA  (ARRAY,  IL,  IR,  INTEGER,  lERR) 

CIA  converts  an  integer  to  a numeric  string  (display  code). 
The  resultant  string  may  contain  no  more  than  15  characters. 

If  the  integer  is  too  large  for  the  space  provided,  an  asterisk 
(*)  is  placed  in  the  IL  position. 

Parameters: 


ARRAY 

Name  of  the  character  string 

IL 

First  character  position  in  ARRAY 

IR 

Last  character  position  in  ARRAY 

INTEGER 

An  integer  to  be  converted 

lERR 

Standard  error  code 

Example : 

If  the  contents  of  the  variable  SHIPNAM  were  the  string 
SHIP,  and  if  the  variable  SHIPNO  were  equal  to  12,  then  the 
statement 

CALL  CIA  (SHIPNAM,  5,  6,  SHIPNO,  lERR) 
when  executed  would  result  in  SHIPNAM  containing  the  string 
SHIP12. 

7 . CAR 

CAR  (REAL,  ARRAY,  U;*  lERR) 

CAR  converts  a numeric  string  (display  code)  to  a real 
number.  The  string  may  contain  no  more  than  20  characters. 

Parameters ; 

REAL  Location  to  receive  the  real  number 
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ARRAY  Name  of  the  character  string  to  be  converted.  The 
string  may  not  contain  embedded  blanks  or  non- 
numeric characters  other  than  E,  *,  . and 
IL  First  character  position  in  ARRAY 

IR  Last  character  position  in  ARRAY 

lERR  Standard  error  code 

Example : 

If  the  contents  of  the  variable  ARRAY  were  ABC5237.00, 
the  statement 

CALL  CAR  (REAL,  ARRAY,  4,  10,  lERR) 
when  executed  would  result  in  REAL  having  the  contents  5237.00 
in  floating  format. 

8.  CRA 

CRA  (ARRAY,  FORMAT,  REAL,  TeRR) 

CRA  converts  a real  number  to  a numeric  string  according 
to  a user-specified  conversion  format.  The  resultant  string 
may  contain  no  more  than  20  characters.  No  format  checking 
is  performed;  legal  formats  for  real  numbers  include  the  E and 
F formats  described  in  the  FORTRAN  Reference  Manual. 

Parameters : 

ARRAY  Name  of  the  character  string 

IL  First  character  position  in  ARRAY 

FORMAT  Name  of  the  variable  containing  the  conversion 

format  ( left- just  if  ied  , H format);  e.g.,  8H(E20.14) 
REAL  A real  number  to  be  converted 

lERR  Standard  error  code 
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9.  CAO 


CAO  (OCTAL,  ARRAY , IL,  ^R,  lERR)  j 

CAO  converts  a numeric  string  (display  code)  to  an  octal  I 

number.  The  string  may  not  contain  more  than  20  characters. 

Parameters: 

OCTAL  Location  to  receive  the  octal  number 

ARRAY  Name  of  the  character  string  to  be  converted.  [ 

IL  First  character  position  in  ARRAY 

IR  Last  character  position  in  ARRAY  1 

lERR  Standard  error  code 

Example: 

If  the  contents  of  the  variable  ARRAY  were  ABC123,  the 
statement 

CALL  CAO  (lOCT,  ARRAY,  4,  6,  lERR) 


when  executed  would  result  in  lOCT  having  the  contents  83 
(i.e.,  123  decimal)  in  fixed  format. 

10.  COA 

COA  (ARRAY,  I_L,  IR,  lOCT,  lERR) 

COA  converts  an  octal  number  to  a numeric  string.  If  the 
number  is  too  large  for  the  string  specified,  an  asterisk  (*) 
is  placed  in  the  IL  position. 

Parameters : 

ARRAY  Name  of  the  character  string 
IL  'St  character  position  in  ARRAY 

IR  ' character  position  in  ARRAY 

lOCT  An  octal  number  to  be  converted 

lERR  Standard  error  code 
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11.  CAD 


CAD  (DOPR,  ARRAY,  H.,  lERR) 

CAD  converts  a numeric  string  (display  code)  to  a double- 
precision real  number.  The  string  may  contain  no  more  than 
30  characters. 

Parameters: 

DOPR  Location  to  receive  the  double-precision  number. 

ARRAY  Name  of  the  character  string  to  be  converted. 

The  string  may  not  contain  embedded  blanks  or 
non-numeric  characters  other  than  D,  +,  . and  -. 

IL  First  character  position  in  ARRAY 

IR  Last  character  position  in  ARRAY 

lERR  Standard  error  code 

12.  CDA 

CDA  (ARRAY,  FORMAT,  DOPR,  Te^) 

CDA  converts  a double-precision  real  number  to  a numeric 
string  according  to  a user-specified  conversion  format.  The 
resultant  string  may  contain  no  more  than  30  characters.  No 
format  checking  is  performed;  the  legal  format  for  double- 
precision numbers  is  described  in  the  FORTRAN  Reference  Manual^^ 
Parameters : 

ARRAY  Name  of  the  character  string 
IL  First  character  position  in  ARRAY 

FORMAT  Name  of  the  variable  containing  the  conversion 
format  ( lef t- j ust i f ied , H format);  e.g., 

8H(D28.22) 
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APPENDIX  H 

PERMANENT  FILE  MANAGEMENT  SUBROUTINES 

When  an  application  program  is  executing,  especially  one 
which  relies  heavily  on  input  and  output  processing  and  file 
handling,  it  may  become  necessary  for  the  program  to 
dynamically  perform  file  functions  ordinarily  accomplished 
by  way  of  job  control  statements.  Towards  this  end,  the 
library  SUBLIB  provides  two  sets  of  file  management  sub- 
routines, one  set  for  files  managed  by  the  SCOPE  system,  and 
one  set  for  files  managed  by  the  COMRADE  Permanent  File 
Management  System  (CPFMS;  see  Appendix  A).  Parameters,  error 
codes,  and  calling  formats  for  a subset  of  the  subroutines 
follow.  Detailed  descriptions  of  all  the  subroutines  are  con- 
tained in  the  COMRADE  Design  Administration  System  Users 
Manual . 

A.  SCOPE  FILE  MANAGEMENT  SUBROUTINES 
1.  Parameter  Identification 
lERR  Error  Code 

LFN  Local  File  Name 

IPFN  Permanent  file  name  (up  to  40  characters) 

ID  User  identifier  (4  characters) 

ITK  Turnkey  password  (up  to  9 characters) 

IRD  Read  password  (up  to  9 characters) 

lEX  Extend  password  (up  to  9 characters) 

IMD  Modify  password  (up  to  9 characters) 

ICN  Control  password  (up  to  9 characters) 
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IMR 


I AC 
ICY 


IRP 


Read/Write  indicator; 

= 0 Read/write 
f 0 Read  only 

Account  number  (10  characters) 

Cycle  number: 

= 0 Highest  cycle  will  be  processed 
= i where  1 li  1999  Cycle  i will  be  processed 
Retention  period  in  days  (must  be  <^999; 
default  is  30) 


2.  Error  Codes 
0 
1 
2 

3 

4 

5 

6 
8 
9 

10 

12 

13 

14 

15 

16 
18 


No  error  detected 
lAC  Illegal 
LFN  already  in  use 
Unknown  LFN 

No  room  for  extra  cycle  (limit  is  5) 
Permanent  file  catalog  full 
No  LFN  or  PFN 

f 

Latest  index  not  written 

File  not  on  a permanent  file  device 

File  not  in  system 

Invalid  cycle  number 

Cycle  number  limit  reached 

Permanent  file  directory  full 

Function  attempted  on  non-permanent  file 

Function  attempted  on  non-local  file 

File  never  assigned  to  a device 


i 

I 


I 
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20 


Permanent  file  already  attached 
File  unavailable 


21 

3.  Calling  Formats 

The  calling  formats  for  subroutines  ATTACH,  CATALOG,  and 
PURGE  are  shown  below;  these  subroutines  may  be  used  by  an 
executing  program  to  attach,  catalog,  and  purge  SCOPE 
permanent  files.  The  calling  formats  for  the  subroutines 
are  nearly  identical.  For  subroutines  ATTACH  and  PURGE,  the 
calling  formats  may  be  truncated  to  include  only  the  required 
parameters  lERR,  LFN,  IPFN,  and  ID;  the  calling  format  for 
CATLOG  may  be  truncated  to  include  the  required  parameters 
lERR,  LFN,  IPFN,  ID,  ITK,  IRD,  lEX,  IMD,  ICN,  IMR,  and  lAC. 

In  any  case,  unused  parameters  should  be  set  to  0. 

CALL  ATTACH  (lERR,  LFN,  IPFN,  ID,  ITK,  IRD,  lEX,  IMD,  ICN, 
IMR,  lAC,  ICY,  IRP) 

CALL  CATLOG  (same  as  ATTACH) 

CALL  PURGE  (same  as  ATTACH) 

B.  CPFMS  FILE  MANAGEMENT  SUBROUTINES 
1.  Parameter  Identification 


lERR 

Error  code 

LFN 

Local  file  name 

L3 

Level-3  name  (as  many 

as  8 characters) 

L4 

Level-4  name  (as  many 

as  8 characters) 

IFACF 

File  access  control 

field  of  7 bits; 

= 0 check  only  file 

access  key  (FAK) 

with  the  file  access  lock  (FAL) 
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IMR  Read/write  indicator: 

= 0 Read  only 
= 1 Read/write 

IPSPW  Pseudo-password  (as  many  as  5 characters) 
= 0 No  password 

IFAL  File  access  lock  of  20  bits 

= 0 No  lock 


Error  codes 
0 
1 
2 

3 

4 

5 

6 

7 

8 

10 

15 

16 
17 
23 


No  error  detected 

Invalid  pseudo-password 

LFN  already  in  use 

Access  for  file  creator  only 

FAK  does  not  agree  with  FAL 

Level  3 name  does  not  exist 

Level  4 name  does  not  exist 

LFN  already  in  list  of  attached  files 

LFN  table  full 

File  busy 

Permanent  file  catalog  full 
Latest  index  not  written 
File  not  on  a permanent  file  device 
Permanent  file  already  attached 


3.  Calling  Formats 

The  calling  formats  for  subroutines  COMATC,  COMCAT,  and 
COMPRG  are  shown;  these  subroutines  may  be  used  by  an  executing 
program  to  attach,  catalog,  and  purge  CPFMS  permanent  files. 
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CALL 

COMATC 

( lERR, 

LFN, 

IMR,  IPSPW) 

CALL 

COMCAT 

( lERR, 

LFN, 

IFACF,  IPSPW,  IFAD 

CALL 

COMPRG 

{ lERR, 

LFN> 

kl' 

IPSPW) 
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DTNSRDC  ISSUES  THREE  TYPES  OF  REPORTS 

1.  DTNSRDC  REPORTS.  A FORMAL  SERIES.  CONTAIN  INFORMATION  OF  PERMANENT  TECH 
NICAL  VALUE.  THEY  CARRY  A CONSECUTIVE  NUMERICAL  IDENTIFICATION  REGARDLESS  OF 
THEIR  CLASSIFICATION  OR  THE  ORIGINATING  DEPARTMENT 

2.  DEPARTMENTAL  REPORTS.  A SEMIFORMAL  SERIES.  CONTAIN  INFORMATION  OF  A PRELIM 
INARY,  TEMPORARY,  OR  PROPRIETARY  NATURE  OR  OF  LIMITED  INTEREST  OR  SIGNIFICANCE 
THEY  CARRY  A DEPARTMENTAL  ALPHANUMERICAL  IDENTIFICATION. 

3.  TECHNICAL  MEMORANDA.  AN  INFORMAL  SERIES,  CONTAIN  TECHNICAL  DOCUMENTATION 
OF  LIMITED  USE  AND  INTEREST.  THEY  ARE  PRIMARILY  WORKING  PAPERS  INTENDED  FOR  IN 
TERNAL  USE.  THEY  CARRY  AN  IDENTIFYING  NUMBER  WHICH  INDICATES  THEIR  TYPE  AND  THE 
NUMERICAL  CODE  OF  THE  ORIGINATING  DEPARTMENT.  ANY  DISTRIBUTION  OUTSIDE  DTNSRDC 
MUST  BE  APPROVED  BY  THE  HEAD  OF  THE  ORIGINATING  DEPARTMENT  ON  A CASE  BY-CASE 
BASIS. 


